Physical drive number to identify the target device. Always zero at single drive system.
29 |
30 |
31 |
32 |
33 |
34 |
Return Values
35 |
This function returns the current drive status flags as the result. For details of the drive status, refer to the disk_status function.
36 |
37 |
38 |
39 |
Description
40 |
This function initializes the storage device and put it ready to generic read/write. When the function succeeded, STA_NOINIT flag in the return value is cleared.
41 |
Remarks: This function needs to be under control of FatFs module. Application program MUST NOT call this function while FatFs is in use, or FAT structure on the volume can be broken. To re-initialize the filesystem, use f_mount function instead.
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.
17 |
18 | typedefstruct {
19 | FFOBJID obj; /* Object identifier */
20 | DWORD dptr; /* Current read/write offset */
21 | DWORD clust; /* Current cluster */
22 | LBA_t sect; /* Current sector */
23 | BYTE* dir; /* Pointer to the current SFN entry in the win[] */
24 | BYTE* fn; /* Pointer to the SFN buffer (in/out) {file[8],ext[3],status[1]} */
25 | #if FF_USE_LFN
26 | DWORD blk_ofs; /* Offset of the entry block (0xFFFFFFFF:Invalid) */
27 | WCHAR* lfn; /* Pointer to the LFN working buffer (in/out) */
28 | #endif
29 | #if FF_USE_FIND
30 | const TCHAR* pat; /* Ponter to the matching pattern */
31 | #endif
32 | } DIR;
33 |
The f_truncate function truncates the file size to the current file read/write pointer. This function has no effect if the file read/write pointer is already pointing end of the file.
The f_closedir function closes an open directory object. After the function succeeded, the directory object is no longer valid and it can be discarded.
47 |
Note that the directory object can also be discarded without this procedure when option FF_FS_LOCK is not enabled. However this is not recommended for future compatibility.
The f_close function closes an open file object. If the file has been changed, the cached information of the file is written back to the volume. After the function succeeded, the file object is no longer valid and it can be discarded.
48 |
Note that if the file object is in read-only mode and FF_FS_LOCK is not enabled, the file object can also be discarded without this procedure. However this is not recommended for future compatibility.
Physical drive number to identify the target device. Always zero in single drive system.
29 |
30 |
31 |
32 |
33 |
34 |
Return Values
35 |
The current drive status is returned in combination of status flags described below. FatFs refers only STA_NOINIT and STA_PROTECT.
36 |
37 |
STA_NOINIT
38 |
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.
39 |
STA_NODISK
40 |
Indicates that no medium in the drive. This is always cleared when the drive is non-removable class. Note that FatFs does not refer this flag.
41 |
STA_PROTECT
42 |
Indicates that the medium is write protected. This is always cleared when the drive has no write protect function. Not valid if STA_NODISK is set.
The f_chdrive function changes only the current drive. The initial value of the current drive number is 0. In Unix style drive prefix configuration, this function will not be needed because f_chdir function changes also the current drive. Note that the current drive is retained in a static variable, so that it also affects other tasks that using the file functions.
69 |
70 |
71 |
--------------------------------------------------------------------------------
/documents/res/app2.c:
--------------------------------------------------------------------------------
1 | /*------------------------------------------------------------/
2 | / Delete a sub-directory even if it contains any file
3 | /-------------------------------------------------------------/
4 | / The delete_node() function is for R0.12+.
5 | / It works regardless of FF_FS_RPATH.
6 | */
7 |
8 |
9 | FRESULT delete_node (
10 | TCHAR* path, /* Path name buffer with the sub-directory to delete */
11 | UINT sz_buff, /* Size of path name buffer (items) */
12 | FILINFO* fno /* Name read buffer */
13 | )
14 | {
15 | UINT i, j;
16 | FRESULT fr;
17 | DIR dir;
18 |
19 |
20 | fr = f_opendir(&dir, path); /* Open the sub-directory to make it empty */
21 | if (fr != FR_OK) return fr;
22 |
23 | for (i = 0; path[i]; i++) ; /* Get current path length */
24 | path[i++] = _T('/');
25 |
26 | for (;;) {
27 | fr = f_readdir(&dir, fno); /* Get a directory item */
28 | if (fr != FR_OK || !fno->fname[0]) break; /* End of directory? */
29 | j = 0;
30 | do { /* Make a path name */
31 | if (i + j >= sz_buff) { /* Buffer over flow? */
32 | fr = 100; break; /* Fails with 100 when buffer overflow */
33 | }
34 | path[i + j] = fno->fname[j];
35 | } while (fno->fname[j++]);
36 | if (fno->fattrib & AM_DIR) { /* Item is a sub-directory */
37 | fr = delete_node(path, sz_buff, fno);
38 | } else { /* Item is a file */
39 | fr = f_unlink(path);
40 | }
41 | if (fr != FR_OK) break;
42 | }
43 |
44 | path[--i] = 0; /* Restore the path name */
45 | f_closedir(&dir);
46 |
47 | if (fr == FR_OK) fr = f_unlink(path); /* Delete the empty sub-directory */
48 | return fr;
49 | }
50 |
51 |
52 |
53 |
54 | int main (void) /* How to use */
55 | {
56 | FRESULT fr;
57 | FATFS fs;
58 | TCHAR buff[256];
59 | FILINFO fno;
60 |
61 |
62 | f_mount(&fs, _T("5:"), 0);
63 |
64 | /* Directory to be deleted */
65 | _tcscpy(buff, _T("5:dir"));
66 |
67 | /* Delete the directory */
68 | fr = delete_node(buff, sizeof buff / sizeof buff[0], &fno);
69 |
70 | /* Check the result */
71 | if (fr) {
72 | _tprintf(_T("Failed to delete the directory. (%u)\n"), fr);
73 | return fr;
74 | } else {
75 | _tprintf(_T("The directory and the contents have successfully been deleted.\n"), buff);
76 | return 0;
77 | }
78 | }
79 |
80 |
81 |
82 |
--------------------------------------------------------------------------------
/documents/doc/fattime.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | FatFs - get_fattime
10 |
11 |
12 |
13 |
14 |
15 |
get_fattime
16 |
The get_fattime function is called to get the current time.
17 |
18 | DWORD get_fattime (void);
19 |
20 |
21 |
22 |
23 |
24 |
Return Value
25 |
Currnet local time shall be returned as bit-fields packed into a DWORD value. The bit fields are as follows:
26 |
27 |
bit31:25
28 |
Year origin from the 1980 (0..127, e.g. 37 for 2017)
29 |
bit24:21
30 |
Month (1..12)
31 |
bit20:16
32 |
Day of the month (1..31)
33 |
bit15:11
34 |
Hour (0..23)
35 |
bit10:5
36 |
Minute (0..59)
37 |
bit4:0
38 |
Second / 2 (0..29, e.g. 25 for 50)
39 |
40 |
41 |
42 |
43 |
44 |
Description
45 |
The get_fattime function shall return any valid time even if the system does not support a real time clock. If a zero is returned, the file will not have a valid timestamp.
79 |
80 |
81 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Middleware FatFS MCU Component
2 |
3 | 
4 |
5 | ## Overview
6 |
7 | **STM32Cube** is an STMicroelectronics original initiative to ease developers' life by reducing efforts, time and cost.
8 |
9 | **STM32Cube** covers the overall STM32 products portfolio. It includes a comprehensive embedded software platform delivered for each STM32 series.
10 | * The CMSIS modules (core and device) corresponding to the ARM(tm) core implemented in this STM32 product.
11 | * The STM32 HAL-LL drivers, an abstraction layer offering a set of APIs ensuring maximized portability across the STM32 portfolio.
12 | * The BSP drivers of each evaluation, discovery, or nucleo board provided for this STM32 series.
13 | * A consistent set of middleware libraries such as RTOS, USB, FatFS, graphics, touch sensing library...
14 | * A full set of software projects (basic examples, applications, and demonstrations) for each board provided for this STM32 series.
15 |
16 | Two models of publication are proposed for the STM32Cube embedded software:
17 | * The monolithic **MCU Package**: all STM32Cube software modules of one STM32 series are present (Drivers, Middleware, Projects, Utilities) in the repository (usual name **STM32Cubexx**, xx corresponding to the STM32 series).
18 | * The **MCU component**: each STM32Cube software module being part of the STM32Cube MCU Package, is delivered as an individual repository, allowing the user to select and get only the required software functions.
19 |
20 | ## Description
21 |
22 | This **stm32_mw_fatfs** MCU component repository is one element **common to all** STM32Cube MCU embedded software packages, providing the **FatFS MCU Middleware** part.
23 |
24 | ## Release note
25 |
26 | * Details about the content of this release are available in the release note [here](https://github.com/STMicroelectronics/stm32_mw_fatfs/blob/master/source/00history.txt).
27 | * Details about the updates made by STMicroelectronics are available in the release note [here](https://github.com/STMicroelectronics/stm32_mw_fatfs/blob/master/source/st_readme.txt).
28 |
29 | ## Compatibility information
30 |
31 | Please refer to the release note in the repository of the STM32Cube **firmware** you are using to know which version of this middleware library to use with other components' versions (**e.g.**, other middleware libraries, drivers). It is **crucial** that you use a consistent set of versions.
32 |
33 | ## Troubleshooting
34 |
35 | Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
36 |
--------------------------------------------------------------------------------
/documents/doc/mkdir.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | FatFs - f_mkdir
10 |
11 |
12 |
13 |
14 |
It continues the search from a previous call to the f_findfirst or f_findnext function. If found, the information about the object is stored into the file information structure. If no item to be read, a null string will be returned into fno->fname[].
68 |
69 |
70 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing guide
2 |
3 | This guide serves as a checklist before contributing to this repository. It mainly focuses on the steps to follow to submit an issue or a pull-request.
4 |
5 | ## 1. Issues
6 |
7 | ### 1.1 Before opening an issue
8 |
9 | Please check the following points before posting an issue:
10 | * Make sure you are using the latest commit (major releases are tagged, but corrections are available as new commits).
11 | * Make sure your issue is a question/feedback/suggestions **related to** the software provided in this repository. Otherwise, please refer to section [3](CONTRIBUTING.md#3-support-requests-and-questions) below.
12 | * Make sure your issue is not already reported/fixed on GitHub or discussed on a previous issue. Do not forget to browse into the **closed** issues.
13 |
14 | ### 1.2 Posting the issue
15 |
16 | When you have checked the previous points, create a new report from the **Issues** tab of this repository. A template is available [here](../../issues/new/choose) to help you report the issue you are facing or the enhancement you would like to propose.
17 |
18 | ## 2. Pull Requests
19 |
20 | ### 2.1 Before opening a pull-request
21 |
22 | STMicrolectronics is happy to receive contributions from the community, based on an initial Contributor License Agreement (CLA) procedure.
23 |
24 | * If you are an individual writing original source code and you are sure **you own the intellectual property**, then you need to sign an Individual [CLA](https://cla.st.com).
25 | * If you work for a company that wants also to allow you to contribute with your work, your company needs to provide a Corporate [CLA](https://cla.st.com) mentioning your GitHub account name.
26 | * If you are not sure that a CLA (Individual or Corporate) has been signed for your GitHub account you can check the [CLA](https://cla.st.com) dedicated page.
27 |
28 | Please note that:
29 | * The Corporate CLA will always take precedence over the Individual CLA.
30 | * One CLA submission is sufficient, for any project proposed by STMicroelectronics.
31 |
32 | ### 2.2 How to proceed
33 |
34 | * We recommend to engage first a communication thru an issue, in order to present your proposal, just to confirm that it corresponds to STMicroelectronics' domain or scope.
35 | * Then fork the project to your GitHub account to further develop your contribution. Please use the latest commit version.
36 | * Please, submit one pull-request per new feature or proposal. This will ease the analysis and the final merge if accepted.
37 |
38 | ## 3. Support requests and questions
39 |
40 | For support requests or any other question related to the product, the tools, the environment, you can submit a post to the **ST Community** on the appropriate topic [page](https://community.st.com/s/topiccatalog).
41 |
--------------------------------------------------------------------------------
/documents/doc/sfile.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | FatFs - FIL
10 |
11 |
12 |
13 |
14 |
15 |
FIL
16 |
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.
17 |
18 |
19 | typedefstruct {
20 | FFOBJID obj; /* Object identifier */
21 | BYTE flag; /* File object status flags */
22 | BYTE err; /* Abort flag (error code) */
23 | FSIZE_t fptr; /* File read/write pointer (Byte offset origin from top of the file) */
24 | DWORD clust; /* Current cluster of fptr (One cluster behind if fptr is on the cluster boundary. Invalid if fptr == 0.) */
25 | LBA_t sect; /* Current data sector (Can be invalid if fptr is on the cluster boundary.)*/
26 | #if !FF_FS_READONLY
27 | LBA_t dir_sect; /* Sector number containing the directory entry */
28 | BYTE* dir_ptr; /* Ponter to the directory entry in the window */
29 | #endif
30 | #if FF_USE_FASTSEEK
31 | DWORD* cltbl; /* Pointer to the cluster link map table (Nulled on file open. Set by application.) */
32 | #endif
33 | #if !FF_FS_TINY
34 | BYTE buf[FF_MAX_SS]; /* File private data transfer buffer (Always valid if fptr is not on the sector boundary but can be invalid if fptr is on the sector boundary.) */
35 | #endif
36 | } FIL;
37 |
18 | int f_putc (
19 | TCHAR chr, /* [IN] A character to write */
20 | FIL* fp/* [IN] File object */
21 | );
22 |
23 |
24 |
25 |
26 |
Parameters
27 |
28 |
chr
29 |
A character to write.
30 |
fp
31 |
Pointer to the open file object structuer.
32 |
33 |
34 |
35 |
36 |
37 |
Return Values
38 |
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, a negative value will be returned.
39 |
40 |
41 |
42 |
43 |
Description
44 |
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 read/written via those functions is selected by FF_STRF_ENCODE. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, cannot be written with this function.
45 |
46 |
47 |
48 |
QuickInfo
49 |
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC >= 1. When FF_USE_STRFUNC == 2, a '\n' is output as '\r'+'\n'.
The f_getcwd function retrieves full path name of the current directory of the current drive. When FF_VOLUMES >= 2, a heading drive prefix is added to the path name. The style of drive prefix depends on FF_STR_VOLUME_ID.
54 |
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 null terminated string to be written. The terminator character will not be written.
30 |
fp
31 |
Pointer to the open file object structure.
32 |
33 |
34 |
35 |
36 |
37 |
Return Value
38 |
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, a negative value will be returned.
39 |
40 |
41 |
42 |
43 |
Description
44 |
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. The characters with wrong encoding or invalid for the output encoding will be lost.
45 |
46 |
47 |
48 |
49 |
QuickInfo
50 |
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC >= 1. When FF_USE_STRFUNC == 2, '\n's contained in the input string are output as '\r'+'\n' each.
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.
18 | FRESULT f_read (
19 | FIL* fp, /* [IN] File object */
20 | void* buff, /* [OUT] Buffer to store read data */
21 | UINT btr, /* [IN] Number of bytes to read */
22 | UINT* br/* [OUT] Number of bytes read */
23 | );
24 |
25 |
26 |
27 |
28 |
Parameters
29 |
30 |
fp
31 |
Pointer to the open file object.
32 |
buff
33 |
Pointer to the buffer to store the read data.
34 |
btr
35 |
Number of bytes to read in range of UINT type. If the file needs to be read fast, it should be read in large chunk as possible.
36 |
br
37 |
Pointer to the UINT variable that receives number of bytes read. This value is always valid after the function call regardless of the function return code. If the return value is equal to btr, the function return code should be FR_OK.
The function starts to read data from the file at the file offset pointed by read/write pointer. The read/write pointer advances as number of bytes read. After the function succeeded, *br should be checked to detect end of the file. In case of *br < btr, it means the read/write pointer hit end of the file during read operation.
When the function succeeded, buff will be returuned.
42 |
43 |
44 |
45 |
46 |
Description
47 |
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.
48 |
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.
49 |
50 |
51 |
52 |
53 |
QuickInfo
54 |
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.
Pointer to the null-terminated string that specifies the logical drive. Null-string specifies the default drive.
31 |
label
32 |
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.
33 |
34 |
Configuration
FF_FS_EXFAT == 0
FF_FS_EXFAT == 1
35 |
FF_USE_LFN == 0
12 items
-
36 |
FF_LFN_UNICODE == 0
12 items
23 items
37 |
FF_LFN_UNICODE == 1,3
12 items
12 items
38 |
FF_LFN_UNICODE == 2
34 items
34 items
39 |
40 |
41 |
vsn
42 |
Pointer to the DWORD variable to store the volume serial number. Set null pointer if this information is not needed.
The f_chdir function changes the current directory of the logical drive. Also the current drive will be changed when in Unix style drive prefix, FF_STR_VOLUME_ID == 2. The current directory of each logical drive is initialized to the root directory on mount.
54 |
Note that the current directory is retained in the each file system object and the current drive is retained in a static variable, so that it also affects other tasks that use the file functions.
67 | /* Change current direcoty of the current drive ("dir1" under root directory) */
68 | f_chdir("/dir1");
69 |
70 | /* Change current direcoty of current drive (parent directory of drive 2) */
71 | f_chdir("2:..");
72 |
73 | /* Change current direcoty of the drive "sdcard" (at DOS/Windows style volume ID) */
74 | f_chdir("sdcard:/dir1");
75 |
76 | /* Change current direcoty of the drive "flash" and set it as current drive (at Unix style volume ID) */
77 | f_chdir("/flash/dir1");
78 |
18 | FRESULT f_write (
19 | FIL* fp, /* [IN] Pointer to the file object structure */
20 | const void* buff, /* [IN] Pointer to the data to be written */
21 | UINT btw, /* [IN] Number of bytes to write */
22 | UINT* bw/* [OUT] Pointer to the variable to return number of bytes written */
23 | );
24 |
25 |
26 |
27 |
28 |
Parameters
29 |
30 |
fp
31 |
Pointer to the open file object structure.
32 |
buff
33 |
Pointer to the data to be written.
34 |
btw
35 |
Specifies number of bytes to write in range of UINT type. If the data needs to be written fast, it should be written in large chunk as possible.
36 |
bw
37 |
Pointer to the UINT variable that receives the number of bytes written. This value is always valid after the function call regardless of the function return code. If the return value is equal to btw, the function return code should be FR_OK.
The function starts to write data to the file at the file offset pointed by read/write pointer. The read/write pointer advances as number of bytes written. After the function succeeded, *bw should be checked to detect the disk full. In case of *bw < btw, it means the volume got full during the write operation. The function can take a time when the volume is full or close to full.
The f_rename function renames and/or moves a file or sub-directory.
17 |
18 | FRESULT f_rename (
19 | const TCHAR* old_name, /* [IN] Old object name */
20 | const TCHAR* new_name/* [IN] New object name */
21 | );
22 |
23 |
24 |
25 |
26 |
Parameters
27 |
28 |
old_name
29 |
Pointer to a null-terminated string that specifies the existing file or sub-directory to be renamed.
30 |
new_name
31 |
Pointer to a null-terminated string that specifies the new object name. A drive number may be specified in this string but it is ignored and assumed as the same drive of the old_name. Any object with this path name except old_name must not be exist, or the function fails with FR_EXIST.
Renames a file or sub-directory and can also move it to other directory in the same volume. The object to be renamed must not be an open object, or the FAT volume can be collapsed. Such the wrong operation is rejected safely when file lock function is enabled.
73 | /* Rename an object in the default drive */
74 | f_rename("oldname.txt", "newname.txt");
75 |
76 | /* Rename an object in the drive 2 */
77 | f_rename("2:oldname.txt", "newname.txt");
78 |
79 | /* Rename an object and move it to another directory in the drive */
80 | f_rename("log.txt", "old/log0001.txt");
81 |
The f_sync function performs the same process as f_close function but the file is left opened and can continue read/write/seek operations to the file. This is suitable for the applications that open files for a long time in write mode, such as data logger. Performing f_sync function in certain interval can minimize the risk of data loss due to a sudden blackout, wrong media removal or unrecoverable disk error. For more information, refer to application note.
48 |
49 | Case 1. Normal write sequence
50 |
51 | Time --> ↓Normal shutdown
52 | OwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwC <Power off>
53 |
54 |
55 | Case 2. Without using f_sync()
56 |
57 | Time --> ↓System crush
58 | Owwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww
59 | |<--------------- All data written will be lost ------------------>|
60 |
61 |
62 | Case 3. Using f_sync()
63 | Time --> ↓System crush
64 | OwwwwwwwwSwwwwwwwwSwwwwwwwwSwwwwwwwwSwwwwwwwwSwwwwwwwwSwwwwwwwwSwwwww
65 | Data after last f_sync will be lost |<->|
66 | O - f_open()
67 | C - f_close()
68 | w - f_write()
69 | S - f_sync()
70 |
71 |
However there is no sense in f_sync function immediataly before f_close function because it performs f_sync function in it. In other words, the differnce between those functions is that the file object is invalidated or not.
The FILINFO structure holds information about the object retrieved by f_readdir, f_findfirst, f_findnext and f_stat function. Be careful in the size of structure when LFN is enabled.
17 |
18 | typedef struct {
19 | FSIZE_t fsize; /* File size */
20 | WORD fdate; /* Last modified date */
21 | WORD ftime; /* Last modified time */
22 | BYTE fattrib; /* Attribute */
23 | #if FF_USE_LFN
24 | TCHAR altname[FF_SFN_BUF + 1]; /* Alternative object name */
25 | TCHAR fname[FF_LFN_BUF + 1]; /* Primary object name */
26 | #else
27 | TCHAR fname[12 + 1]; /* Object name */
28 | #endif
29 | } FILINFO;
30 |
31 |
32 |
33 |
Members
34 |
35 |
fsize
36 |
Size of the file in unit of byte. FSIZE_t is an alias of integer type either DWORD(32-bit) or QWORD(64-bit) depends on the configuration option FF_FS_EXFAT. Do not care if the item is a sub-directory.
37 |
fdate
38 |
The date when the file was modified or the directory was created.
39 |
40 |
bit15:9
41 |
Year origin from 1980 (0..127)
42 |
bit8:5
43 |
Month (1..12)
44 |
bit4:0
45 |
Day (1..31)
46 |
47 |
48 |
ftime
49 |
The time when the file was modified or the directory was created.
50 |
51 |
bit15:11
52 |
Hour (0..23)
53 |
bit10:5
54 |
Minute (0..59)
55 |
bit4:0
56 |
Second / 2 (0..29)
57 |
58 |
59 |
fattrib
60 |
The attribute flags in combination of:
61 |
62 |
Flag
Meaning
63 |
AM_RDO
Read-only. Write mode open and deleting is rejected.
64 |
AM_HID
Hidden. Should not be shown in normal directory listing.
65 |
AM_SYS
System. Used by system and should not be accessed.
66 |
AM_ARC
Archive. Set on new creation or any modification to the file.
67 |
AM_DIR
Directory. This is not a file but a sub-directory container.
68 |
69 |
70 |
fname[]
71 |
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.
72 |
altname[]
73 |
Alternative object name is stored if available. This member is not available in non-LFN configuration.
77 |
78 |
79 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | In the interest of fostering an open and welcoming environment, we as
6 | contributors and maintainers pledge to making participation in our project and
7 | our community a harassment-free experience for everyone, regardless of age, body
8 | size, disability, ethnicity, sex characteristics, gender identity and expression,
9 | level of experience, education, socio-economic status, nationality, personal
10 | appearance, race, religion, or sexual identity and orientation.
11 |
12 | ## Our Standards
13 |
14 | Examples of behavior that contributes to creating a positive environment
15 | include:
16 |
17 | * Using welcoming and inclusive language
18 | * Being respectful of differing viewpoints and experiences
19 | * Gracefully accepting constructive criticism
20 | * Focusing on what is best for the community
21 | * Showing empathy towards other community members
22 |
23 | Examples of unacceptable behavior by participants include:
24 |
25 | * The use of sexualized language or imagery and unwelcome sexual attention or
26 | advances
27 | * Trolling, insulting/derogatory comments, and personal or political attacks
28 | * Public or private harassment
29 | * Publishing others' private information, such as a physical or electronic
30 | address, without explicit permission
31 | * Other conduct which could reasonably be considered inappropriate in a
32 | professional setting
33 |
34 | ## Our Responsibilities
35 |
36 | Project maintainers are responsible for clarifying the standards of acceptable
37 | behavior and are expected to take appropriate and fair corrective action in
38 | response to any instances of unacceptable behavior.
39 |
40 | Project maintainers have the right and responsibility to remove, edit, or
41 | reject comments, commits, code, wiki edits, issues, and other contributions
42 | that are not aligned to this Code of Conduct, or to ban temporarily or
43 | permanently any contributor for other behaviors that they deem inappropriate,
44 | threatening, offensive, or harmful.
45 |
46 | ## Scope
47 |
48 | This Code of Conduct applies both within project spaces and in public spaces
49 | when an individual is representing the project or its community. Examples of
50 | representing a project or community include using an official project e-mail
51 | address, posting via an official social media account, or acting as an appointed
52 | representative at an online or offline event. Representation of a project may be
53 | further defined and clarified by project maintainers.
54 |
55 | ## Enforcement
56 |
57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
58 | reported by contacting the project team at https://www.st.com/content/st_com/en/contact-us.html. All
59 | complaints will be reviewed and investigated and will result in a response that
60 | is deemed necessary and appropriate to the circumstances. The project team is
61 | obligated to maintain confidentiality with regard to the reporter of an incident.
62 | Further details of specific enforcement policies may be posted separately.
63 |
64 | Project maintainers who do not follow or enforce the Code of Conduct in good
65 | faith may face temporary or permanent repercussions as determined by other
66 | members of the project's leadership.
67 |
68 | ## Attribution
69 |
70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72 |
73 | [homepage]: https://www.contributor-covenant.org
74 |
75 | For answers to common questions about this code of conduct, see
76 | https://www.contributor-covenant.org/faq
77 |
--------------------------------------------------------------------------------
/source/ffsystem_template.c:
--------------------------------------------------------------------------------
1 | /*------------------------------------------------------------------------*/
2 | /* A Sample Code of User Provided OS Dependent Functions for FatFs */
3 | /*------------------------------------------------------------------------*/
4 |
5 | #include "ff.h"
6 |
7 |
8 | #if FF_USE_LFN == 3 /* Use dynamic memory allocation */
9 |
10 | /*------------------------------------------------------------------------*/
11 | /* Allocate/Free a Memory Block */
12 | /*------------------------------------------------------------------------*/
13 |
14 |
15 | void* ff_memalloc ( /* Returns pointer to the allocated memory block (null if not enough core) */
16 | UINT msize /* Number of bytes to allocate */
17 | )
18 | {
19 | void* mem_ptr = NULL; /* Memory block to be allocated */
20 |
21 | return mem_ptr;
22 | }
23 |
24 |
25 | void ff_memfree (
26 | void* mblock /* Pointer to the memory block to free (no effect if null) */
27 | )
28 | {
29 | free(mblock); /* Free the memory block */
30 | }
31 |
32 | #endif
33 |
34 |
35 |
36 |
37 | #if FF_FS_REENTRANT /* Mutal exclusion */
38 | /*------------------------------------------------------------------------*/
39 | /* Create a Mutex */
40 | /*------------------------------------------------------------------------*/
41 | /* This function is called in f_mount function to create a new mutex
42 | / or semaphore for the volume. When a 0 is returned, the f_mount function
43 | / fails with FR_INT_ERR.
44 | */
45 |
46 | int ff_mutex_create ( /* Returns 1:Function succeeded or 0:Could not create the mutex */
47 | int vol /* Mutex ID: Volume mutex (0 to FF_VOLUMES - 1) or system mutex (FF_VOLUMES) */
48 | )
49 | {
50 | return 1;
51 | }
52 |
53 |
54 | /*------------------------------------------------------------------------*/
55 | /* Delete a Mutex */
56 | /*------------------------------------------------------------------------*/
57 | /* This function is called in f_mount function to delete a mutex or
58 | / semaphore of the volume created with ff_mutex_create function.
59 | */
60 |
61 | void ff_mutex_delete ( /* Returns 1:Function succeeded or 0:Could not delete due to an error */
62 | int vol /* Mutex ID: Volume mutex (0 to FF_VOLUMES - 1) or system mutex (FF_VOLUMES) */
63 | )
64 | {
65 | return 1;
66 | }
67 |
68 |
69 | /*------------------------------------------------------------------------*/
70 | /* Request a Grant to Access the Volume */
71 | /*------------------------------------------------------------------------*/
72 | /* This function is called on enter file functions to lock the volume.
73 | / When a 0 is returned, the file function fails with FR_TIMEOUT.
74 | */
75 |
76 | int ff_mutex_take ( /* Returns 1:Succeeded or 0:Timeout */
77 | int vol /* Mutex ID: Volume mutex (0 to FF_VOLUMES - 1) or system mutex (FF_VOLUMES) */
78 | )
79 | {
80 | return 1;
81 | }
82 |
83 |
84 |
85 | /*------------------------------------------------------------------------*/
86 | /* Release a Grant to Access the Volume */
87 | /*------------------------------------------------------------------------*/
88 | /* This function is called on leave file functions to unlock the volume.
89 | */
90 |
91 | void ff_mutex_give (
92 | int vol /* Mutex ID: Volume mutex (0 to FF_VOLUMES - 1) or system mutex (FF_VOLUMES) */
93 | )
94 | {
95 | return 1;
96 | }
97 |
98 | #endif /* FF_FS_REENTRANT */
99 |
100 |
--------------------------------------------------------------------------------
/documents/doc/setlabel.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | FatFs - f_setlabel
10 |
11 |
12 |
13 |
14 |
15 |
f_setlabel
16 |
The f_setlabel function sets/removes the label of a volume.
17 |
18 | FRESULT f_setlabel (
19 | const TCHAR* label/* [IN] Volume label to be set */
20 | );
21 |
22 |
23 |
24 |
25 |
Parameters
26 |
27 |
label
28 |
Pointer to the null-terminated string that specifies the volume label to be set.
When the string has a drive prefix, the volume label will be set to the volume specified by the drive prefix. Unix style volume ID cannot be used to specify the volume. If drive number is not specified, 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 is as shown below:
53 |
54 |
Up to 11 bytes long as conversion of OEM code page at FAT volume.
55 |
Up to 11 characters long at exFAT volume.
56 |
Allowable characters for FAT volume are: characters allowed for SFN excludes dot. Low-case characters are up converted.
57 |
Allowable characters for exFAT volume are: characters allowed for LFN includes dot. Low-case characters are preserved.
58 |
Spaces can be embedded anywhere in the volume label. Trailing spaces are truncated off at FAT volume.
59 |
60 |
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.
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. In case of 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 disk_write function is called to write data to the storage device.
17 |
18 | DRESULT disk_write (
19 | BYTE pdrv, /* [IN] Physical drive number */
20 | const BYTE* buff, /* [IN] Pointer to the data to be written */
21 | LBA_t sector, /* [IN] Sector number to write from */
22 | UINT count/* [IN] Number of sectors to write */
23 | );
24 |
25 |
26 |
27 |
28 |
Parameters
29 |
30 |
pdrv
31 |
Physical drive number to identify the target device.
32 |
buff
33 |
Pointer to the first item of the byte array to be written. The size of data to be written is sector size * count bytes.
34 |
sector
35 |
Start sector number in LBA. The data type LBA_t is an alias of DWORD or QWORD depends on the configuration option.
36 |
count
37 |
Number of sectors to write.
38 |
39 |
40 |
41 |
42 |
43 |
Return Values
44 |
45 |
RES_OK (0)
46 |
The function succeeded.
47 |
RES_ERROR
48 |
An unrecoverable hard error occured during the write operation.
49 |
RES_WRPRT
50 |
The medium is write protected.
51 |
RES_PARERR
52 |
Invalid parameter.
53 |
RES_NOTRDY
54 |
The device has not been initialized.
55 |
56 |
57 |
58 |
59 |
60 |
Description
61 |
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.
62 |
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.
63 |
FatFs expects delayed write function of 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. But 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.
64 |
Remarks: Application program MUST NOT call this function, or FAT structure on the 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.
17 |
18 | typedefstruct {
19 | BYTE fs_type; /* FAT type (0, FS_FAT12, FS_FAT16, FS_FAT32 or FS_EXFAT) */
20 | BYTE pdrv; /* Hosting physical drive of this volume */
21 | BYTE n_fats; /* Number of FAT copies (1,2) */
22 | BYTE wflag; /* win[] flag (b0:win[] is dirty) */
23 | BYTE fsi_flag; /* FSINFO flags (b7:Disabled, b0:Dirty) */
24 | WORD id; /* Volume mount ID */
25 | WORD n_rootdir; /* Number of root directory entries (FAT12/16) */
26 | WORD csize; /* Sectors per cluster */
27 | #if FF_MAX_SS != FF_MIN_SS
28 | WORD ssize; /* Sector size (512,1024,2048 or 4096) */
29 | #endif
30 | #if FF_FS_EXFAT
31 | BYTE* dirbuf; /* Directory entry block scratchpad buffer */
32 | #endif
33 | #if FF_FS_REENTRANT
34 | FF_SYNC_t sobj; /* Identifier of sync object */
35 | #endif
36 | #if !FF_FS_READONLY
37 | DWORD last_clust; /* FSINFO: Last allocated cluster (0xFFFFFFFF if invalid) */
38 | DWORD free_clust; /* FSINFO: Number of free clusters (0xFFFFFFFF if invalid) */
39 | #endif
40 | #if FF_FS_RPATH
41 | DWORD cdir; /* Cluster number of current directory (0:root) */
42 | #if FF_FS_EXFAT
43 | DWORD cdc_scl; /* Containing directory start cluster (invalid when cdir is 0) */
44 | DWORD cdc_size; /* b31-b8:Size of containing directory, b7-b0: Chain status */
45 | DWORD cdc_ofs; /* Offset in the containing directory (invalid when cdir is 0) */
46 | #endif
47 | #endif
48 | DWORD n_fatent; /* Number of FAT entries (Number of clusters + 2) */
49 | DWORD fsize; /* Sectors per FAT */
50 | LBA_t volbase; /* Volume base LBA */
51 | LBA_t fatbase; /* FAT base LBA */
52 | LBA_t dirbase; /* Root directory base (LBA|Cluster) */
53 | LBA_t database; /* Data base LBA */
54 | LBA_t winsect; /* Sector LBA appearing in the win[] */
55 | BYTE win[FF_MAX_SS]; /* Disk access window for directory, FAT (and file data at tiny cfg) */
56 | } FATFS;
57 |
61 |
62 |
63 |
--------------------------------------------------------------------------------
/source/ff_gen_drv.c:
--------------------------------------------------------------------------------
1 | /**
2 | ******************************************************************************
3 | * @file ff_gen_drv.c
4 | * @author MCD Application Team
5 | * @brief FatFs generic low level driver.
6 | ******************************************************************************
7 | * @attention
8 | *
9 | * Copyright (c) 2023 STMicroelectronics.
10 | * All rights reserved.
11 | *
12 | * This software is licensed under terms that can be found in the st_license.txt
13 | * file in the root directory of this software component.
14 | * If no st_license.txt file comes with this software, it is provided AS-IS.
15 | *
16 | ******************************************************************************
17 | */
18 |
19 | /* Includes ------------------------------------------------------------------*/
20 | #include "ff_gen_drv.h"
21 |
22 | /* Private typedef -----------------------------------------------------------*/
23 | /* Private define ------------------------------------------------------------*/
24 | /* Private variables ---------------------------------------------------------*/
25 | Disk_drvTypeDef disk = {{0},{0},{0},0};
26 |
27 | /* Private function prototypes -----------------------------------------------*/
28 | /* Private functions ---------------------------------------------------------*/
29 |
30 | /**
31 | * @brief Links a compatible diskio driver/lun id and increments the number of active
32 | * linked drivers.
33 | * @note The number of linked drivers (volumes) is up to 10 due to FatFs limits.
34 | * @param drv: pointer to the disk IO Driver structure
35 | * @param path: pointer to the logical drive path
36 | * @param lun : only used for USB Key Disk to add multi-lun management
37 | else the parameter must be equal to 0
38 | * @retval Returns 0 in case of success, otherwise 1.
39 | */
40 | uint8_t FATFS_LinkDriverEx(const Diskio_drvTypeDef *drv, char *path, uint8_t lun)
41 | {
42 | uint8_t ret = 1;
43 | uint8_t DiskNum = 0;
44 |
45 | if(disk.nbr < FF_VOLUMES)
46 | {
47 | disk.is_initialized[disk.nbr] = 0;
48 | disk.drv[disk.nbr] = drv;
49 | disk.lun[disk.nbr] = lun;
50 | DiskNum = disk.nbr++;
51 | path[0] = DiskNum + '0';
52 | path[1] = ':';
53 | path[2] = '/';
54 | path[3] = 0;
55 | ret = 0;
56 | }
57 |
58 | return ret;
59 | }
60 |
61 | /**
62 | * @brief Links a compatible diskio driver and increments the number of active
63 | * linked drivers.
64 | * @note The number of linked drivers (volumes) is up to 10 due to FatFs limits
65 | * @param drv: pointer to the disk IO Driver structure
66 | * @param path: pointer to the logical drive path
67 | * @retval Returns 0 in case of success, otherwise 1.
68 | */
69 | uint8_t FATFS_LinkDriver(const Diskio_drvTypeDef *drv, char *path)
70 | {
71 | return FATFS_LinkDriverEx(drv, path, 0);
72 | }
73 |
74 | /**
75 | * @brief Unlinks a diskio driver and decrements the number of active linked
76 | * drivers.
77 | * @param path: pointer to the logical drive path
78 | * @param lun : not used
79 | * @retval Returns 0 in case of success, otherwise 1.
80 | */
81 | uint8_t FATFS_UnLinkDriverEx(char *path, uint8_t lun)
82 | {
83 | uint8_t DiskNum = 0;
84 | uint8_t ret = 1;
85 |
86 | if(disk.nbr >= 1)
87 | {
88 | DiskNum = path[0] - '0';
89 | if(disk.drv[DiskNum] != 0)
90 | {
91 | disk.drv[DiskNum] = 0;
92 | disk.lun[DiskNum] = 0;
93 | disk.nbr--;
94 | ret = 0;
95 | }
96 | }
97 |
98 | return ret;
99 | }
100 |
101 | /**
102 | * @brief Unlinks a diskio driver and decrements the number of active linked
103 | * drivers.
104 | * @param path: pointer to the logical drive path
105 | * @retval Returns 0 in case of success, otherwise 1.
106 | */
107 | uint8_t FATFS_UnLinkDriver(char *path)
108 | {
109 | return FATFS_UnLinkDriverEx(path, 0);
110 | }
111 |
112 | /**
113 | * @brief Gets number of linked drivers to the FatFs module.
114 | * @param None
115 | * @retval Number of attached drivers.
116 | */
117 | uint8_t FATFS_GetAttachedDriversNbr(void)
118 | {
119 | return disk.nbr;
120 | }
121 |
--------------------------------------------------------------------------------
/documents/doc/dread.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 | FatFs - disk_read
10 |
11 |
12 |
13 |
14 |
15 |
disk_read
16 |
The disk_read function is called to read data from the storage device.
17 |
18 | DRESULT disk_read (
19 | BYTE pdrv, /* [IN] Physical drive number */
20 | BYTE* buff, /* [OUT] Pointer to the read data buffer */
21 | LBA_t sector, /* [IN] Start sector number */
22 | UINT count/* [IN] Number of sectros to read */
23 | );
24 |
25 |
26 |
27 |
28 |
Parameters
29 |
30 |
pdrv
31 |
Physical drive number to identify the target device.
32 |
buff
33 |
Pointer to the first item of the byte array to store read data. Size of read data will be the sector size * count bytes.
34 |
sector
35 |
Start sector number in LBA. The data type LBA_t is an alias of DWORD or QWORD depends on the configuration option.
36 |
count
37 |
Number of sectors to read.
38 |
39 |
40 |
41 |
42 |
43 |
Return Value
44 |
45 |
RES_OK (0)
46 |
The function succeeded.
47 |
RES_ERROR
48 |
An unrecoverable hard error occured during the read operation.
49 |
RES_PARERR
50 |
Invalid parameter.
51 |
RES_NOTRDY
52 |
The device has not been initialized.
53 |
54 |
55 |
56 |
57 |
58 |
Description
59 |
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 512 to 4096 bytes. When FatFs is configured for fixed sector size (FF_MIN_SS == FF_MAX_SS, this is the most case), the generic read/write function must work at this sector size only. 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 after disk_initialize function succeeds.
60 |
There are some considerations about the memory addres passed via buff. It is not that always aligned with the word boundary, because the argument is defined as BYTE*. The unaligned transfer 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. If it is the case, there are some workarounds described below to avoid this issue.
61 |
62 |
Convert word transfer to byte transfer with some trick in this function. - Recommended.
63 |
On the f_read() calls, avoid long read request that includes a whole of sector. - Any direct transfer never occures.
64 |
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.
65 |
66 |
Also the memory area may be out of reach in DMA. This is the case if it is located on the tightly coupled memory which is usually used for stack. Use double buffered transfer, or avoid to define file I/O buffer, FATFS and FIL structure as local variables where on the stack.
67 |
Generally, a multiple sector read request must not be split into single sector transactions to the storage device, or read throughput gets worse.
The f_stat function checks the existence of a file or sub-directory in the directory. If it is not exist, the function returns with FR_NO_FILE. If it is exist, the function returns with FR_OK and the informations about the object, size, timestamp and attribute, is stored to the file information structure. For details of the file information, refer to the FILINFO structure and f_readdir function.
58 |
Note that the file information comes from the meta data in the directory. If the file has been opend and modified, the file will need to be synched or closed in order to obtain the latest file information.
Specifies the physical drive to be divided. This is not the logical drive number but the drive identifier passed to the low level disk functions.
31 |
ptbl
32 |
List of partition size to create on the drive. The data type LBA_t is an alias of DWORD or QWORD depends on the configuration option FF_LBA64.
33 |
work
34 |
Pointer to the function work area. The size must be at least FF_MAX_SS bytes. When a null pointer is given with FF_USE_LFN = 3, a memory block is obtained in this function for the working buffer.
The f_fdisk function creates partitions on the physical drive. The partitioning format can be in generic MBR or GPT. The partition map table specifies how to divide the physical drive. The first item specifies the size of the first partition and the partitions are located on the drive in order of from the first item. When the value of item is less than or equal to 100, it specifies the partition size in percentage of the entire drive space. When it is larger than 100, it specifies number of sectors. The partition map table is terminated by a zero, no space is remaining for next allocation or 4th partition is created in MBR format. If the specified size is larger than remaining space on the drive, the partition is truncated at end of the drive.
53 |
By default, partitions are created in MBR format. It can create upto four primary partitions on a drive. GPT format is used to create the partitions when 64-bit LBA is enabled (FF_LBA64 = 1) and the drive size is equal to or larger than FF_MIN_GPT sectors. It can create over ten partitions on a drive.
Number of bytes in size to prepare or allocate for the file. 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.
34 |
opt
35 |
Allocation mode. Prepare to allocate (0) or Allocate now (1).
The f_expand function prepares or allocates a contiguous data area to the file. When opt is 1, the data area is allocated to the file in this function. Unlike expansion of file size by f_lseek function, the file must be truncated prior to use this function and read/write pointer of the file stays at offset 0 after the function call. The file content allocated with this function is undefined, because no data is written to the file in this process. The function can fail with FR_DENIED due to some reasons below.
56 |
57 |
No free contiguous space was found.
58 |
Size of the file was not zero.
59 |
The file has been opened in read-only mode.
60 |
Not allowable file size. (>= 4 GB on FAT volume)
61 |
62 |
When opt is 0, the function finds a contiguous data area and set it as suggested point for next allocation. The subsequent cluster allocation begins at top of the contiguous area found by this function. Thus the file allocation is guaranteed be contiguous and without allocation delay until the file size reaches this size unless any other changes to the volume is performed.
63 |
The contiguous file has an advantage for time-critical read/write operations. It eliminates some overheads in the filesystem and the storage device caused by random access for fragmented file.
64 |
Also the contiguous file can be easily accessed directly via low-level disk functions. However, this is not recommended in consideration of portability and future compatibility. If the file has not been confirmed be contiguous, use this function to examine if the file is contiguous or not.
65 |
66 |
67 |
68 |
QuickInfo
69 |
Available when FF_USE_EXPAND == 1 and FF_FS_READONLY == 0.
70 |
71 |
72 |
73 |
74 |
Example
75 |
76 | /* Creating a contiguous file */
77 |
78 | /* Create a new file */
79 | res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS);
80 | if (res) { /* Check if the file has been opened */
81 | free(fp);
82 | die("Failed to open the file.");
83 | }
84 |
85 | /* Alloacte a 100 MiB of contiguous area to the file */
86 | res = f_expand(fp, 104857600, 1);
87 | if (res) { /* Check if the file has been expanded */
88 | f_close(fp);
89 | free(fp);
90 | die("Failed to allocate contiguous area.");
91 | }
92 |
93 | /* Now you have a contiguous file accessible with fp */
94 |
95 |
96 |
97 | /* Accessing the contiguous file via low-level disk functions */
98 |
99 | /* Get physical location of the file data */
100 | drv = fp->obj.fs->pdrv;
101 | lba = fp->obj.fs->database + fp->obj.fs->csize * (fp->obj.sclust - 2);
102 |
103 | /* Write 2048 sectors from top of the file at a time */
104 | res = disk_write(drv, buffer, lba, 2048);
105 |
106 |
The f_forward function reads the data from the file and forward it to the outgoing stream. This function is suitable for small memory system, because it does not require any data buffer in the application module. The file pointer of the file object advances in number of bytes forwarded. In case of *bf is less than btf without error, it means the requested size of data could not be transferred due to end of file or stream goes busy during data transfer.
70 | /*------------------------------------------------------------------------*/
71 | /* Sample code of data transfer function to be called back from f_forward */
72 | /*------------------------------------------------------------------------*/
73 |
74 | UINT out_stream ( /* Returns number of bytes sent or stream status */
75 | const BYTE *p, /* Pointer to the data block to be sent */
76 | UINT btf /* >0: Transfer call (Number of bytes to be sent). 0: Sense call */
77 | )
78 | {
79 | UINT cnt = 0;
80 |
81 |
82 | if (btf == 0) { /* Sense call */
83 | /* Return stream status (0: Busy, 1: Ready) */
84 | /* When once it returned ready to sense call, it must accept a byte at least */
85 | /* at subsequent transfer call, or f_forward will fail with FR_INT_ERR. */
86 | if (FIFO_READY) cnt = 1;
87 | }
88 | else { /* Transfer call */
89 | do { /* Repeat while there is any data to be sent and the stream is ready */
90 | FIFO_PORT = *p++;
91 | cnt++;
92 | } while (cnt < btf && FIFO_READY);
93 | }
94 |
95 | return cnt;
96 | }
97 |
98 |
99 | /*------------------------------------------------------------------------*/
100 | /* Sample code using f_forward function */
101 | /*------------------------------------------------------------------------*/
102 |
103 | FRESULT play_file (
104 | char *fn /* Pointer to the audio file name to be played */
105 | )
106 | {
107 | FRESULT rc;
108 | FIL fil;
109 | UINT dmy;
110 |
111 | /* Open the audio file in read only mode */
112 | rc = f_open(&fil, fn, FA_READ);
113 | if (rc) return rc;
114 |
115 | /* Repeat until the file pointer reaches end of the file */
116 | while (rc == FR_OK && !f_eof(&fil)) {
117 |
118 | /* some processes... */
119 |
120 | /* Fill output stream periodicaly or on-demand */
121 | rc = f_forward(&fil, out_stream, 1000, &dmy);
122 | }
123 |
124 | /* Close the file and return */
125 | f_close(&fil);
126 | return rc;
127 | }
128 |
The f_findfirst function searches a directroy for an item.
17 |
18 | FRESULT f_findfirst (
19 | DIR* dp, /* [OUT] Poninter to the directory object */
20 | FILINFO* fno, /* [OUT] Pointer to the file information structure */
21 | const TCHAR* path, /* [IN] Pointer to the directory name to be opened */
22 | const TCHAR* pattern/* [IN] Pointer to the matching pattern string */
23 | );
24 |
Pointer to the null-terminated string that specifies the directory name to be opened.
36 |
pattern
37 |
Pointer to the nul-terminated string that specifies the name matching pattern to be searched for. It is referred by also subsequent f_findnext function, so that the string must be valid while the successive function calls.
After the directory specified by path could be opened, it starts to search the directory for items with the matching pattern specified by pattern. If the first item is found, the information about the item is stored into the file information structure fno. If not found, fno->fname[] has a null string.
65 |
The matching pattern string can contain wildcards. For example:
66 |
67 |
? - An any character.
68 |
??? - An any string in length of three characters.
69 |
* - An any string in length of zero or longer.
70 |
????* - An any string in length of four characters or longer.
71 |
72 |
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.
73 |
74 |
"*.*" does not match any name without extension while it matches any name with or without extension in standard systems.
75 |
Any pattern terminated with a dot does not match any name while it matches the name without extensiton in standard systems.
76 |
DBCS extended characters are compared in case-sensitive when LFN is enabled with !FF_LFN_UNICODE.
The f_readdir function reads a directory item, informations about the object, from the open directory. Items in the directory can be read in sequence by f_readdir function calls. When all items in the directory have been read and no item to read, a null 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. The f_rewinddir function is implemented as a macro.
When 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 a reason listed below, short file name is stored to the fname[] and the altname[] has a null string.
61 |
62 |
The item has no LFN. (Not the case in exFAT volume)
63 |
FF_MAX_LFN is insufficient to handle the LFN. (Not the case in FF_MAX_LFN == 255)
The LFN contains some character not defined in current CP. (Not the case in FF_LFN_UNICODE != 0)
66 |
67 |
There is an issue on read directories in 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 as the file name to indicate that the object is not accessible. To avoid this problem, configure FatFs FF_LFN_UNICODE != 0 and FF_MAX_LFN == 255 to support the full feature of LFN specification.
68 |
Dot entries ("." and "..") in the sub-directory of FAT volume are filtered out and they will never appear in the read items because exFAT lacks dot entries in the sub-directory.