FatFs 常用 API 详细记录

FatFs 常用 API 详细记录

f_mount - 注册/注销卷的工作区域

函数原型

f_mount功能为 FatFs 模块提供了工作区。

FRESULT f_mount (   FATFS*       fs,    /* [IN] Filesystem object */   
                    const TCHAR* path,  /* [IN] Logical drive number */   
                    BYTE         opt    /* [IN] Initialization option */ ); 

FRESULT f_unmount (   const TCHAR* path   /* [IN] Logical drive number */ );

参数

fs：指向要注册和清除的文件系统对象的指针。空指针注销已注册的文件系统对象。
path：指向指定逻辑驱动器的空终止字符串的指针。不带驱动器编号的字符串表示默认驱动器。
opt：安装选项。0：现在不装入（首次访问卷时装入），1：强制装入卷以检查它是否已准备好工作。

返回值

FR_OK、FR_INVALID_DRIVE、FR_DISK_ERR、FR_NOT_READY、FR_NOT_ENABLED、FR_NO_FILESYSTEM

描述

FatF 需要每个逻辑驱动器（FAT 卷）的工作区（文件系统对象）。在执行任何文件/目录操作之前，需要向逻辑驱动器的f_mount函数注册文件系统对象。文件/目录 API 函数在此过程后即可开始工作。某些卷管理功能（f_mkfs、f_fdisk和f_setcp）不需要文件系统对象。
f_mount函数将文件系统对象注册/注销到 FatFs 模块，如下所示：

1. 确定由路径指定的逻辑驱动器。
2. 清除和注销卷的注册工作区（如果存在）。
3. 如果 fs 不为 NULL，则清除新工作区并将其注册到卷。
4. 如果指定了强制装入，则对卷执行卷装入过程。
   如果逻辑驱动器上有任何打开的文件或目录对象，则该对象将被此函数失效。
   如果未指定强制安装（选择 = 0），则无论物理驱动器状态如何，此功能始终成功。它仅清除（取消初始化）给定的工作区域并将其地址注册到内部表，并且在此功能中不执行物理驱动器的活动。如果未初始化文件系统对象，则将在后续 file/directroy 函数上尝试卷装入过程。（延迟安装）当满足以下任一条件时，卷装入过程，初始化相应的物理驱动器，在其中查找FAT卷，然后初始化工作区，将在后续文件/目录功能中执行。
   ● 文件系统对象尚未初始化。它由f_mount函数取消初始化。
   ● 物理驱动器未初始化。它通过系统重置或介质移除来取消初始化。
   如果强制挂载 （opt = 1） 的函数因FR_NOT_READY而失败，则表示文件系统对象已成功注册，但卷当前尚未准备好工作。卷装入过程将在后续的文件/直接功能上尝试。
   如果磁盘 I/O 层的实现缺少异步介质更改检测，则应用程序需要在每次介质更改后执行f_mount功能，以强制清除文件系统对象。
   要注销工作区，请为 fs 指定 NULL，然后可以放弃该工作区。f_unmount函数作为宏实现。
   #define f_unmount(path) f_mount(0, path, 0)

使用条件

f_open - 打开/创建文件

函数原型

f_open函数打开一个文件。

FRESULT f_open (   FIL* fp,     /* [OUT] Pointer to the file object structure */  
                   const TCHAR* path,    /* [IN] File name */   
                   BYTE mode             /* [IN] Mode flags */ );

参数

fp：指向空白文件对象结构的指针。
path：指向以 null 结尾的字符串的指针，该字符串指定要打开或创建的文件名。
mode：指定文件的访问类型和打开方法的模式标志。它由以下标志的组合定。

标志	意义
FA_READ	指定对文件的读取访问权限。可以从文件中读取数据。
FA_WRITE	指定对文件的写入访问权限。数据可以写入文件。与FA_READ结合使用，实现读写访问。
FA_OPEN_EXISTING	打开一个文件。如果文件不存在，则该函数将失败。（默认值）
FA_CREATE_NEW	创建新文件。如果文件存在，则该函数将失败并显示FR_EXIST。
FA_CREATE_ALWAYS	创建新文件。如果文件存在，它将被截断并覆盖。
FA_OPEN_ALWAYS	打开文件（如果存在）。如果没有，将创建一个新文件。
FA_OPEN_APPEND	与FA_OPEN_ALWAYS相同，只是读/写指针设置在文件的末尾。

返回值

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_INVALID_OBJECT, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES

描述

f_open函数打开一个文件并创建一个文件对象。文件对象是对文件执行后续操作的标识符。打开的文件应在会话后关闭f_close功能的文件访问。如果在断电之前对文件进行了任何更改但未关闭，请移除或重新装载介质，或者文件可以折叠。
如果需要打开重复的文件，请仔细阅读此处。但是，始终禁止重复打开具有任何写入模式标志的文件。

使用条件

随时可用。当FF_FS_READONLY == 1 时，只有 FA_READ 和 FA_OPEN_EXISTING 可用于模式标志。

f_close - 关闭打开的文件

函数原型

f_close函数关闭打开的文件。

FRESULT f_close (   FIL* fp     /* [IN] Pointer to the file object */ ); 

参数

fp：指向要关闭的打开的文件对象结构的指针。

返回值

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_INVALID_OBJECT, FR_TIMEOUT

描述

f_close函数关闭打开的文件对象。如果文件已更改，则文件的缓存信息将写回卷。函数成功后，文件对象不再有效，可以将其丢弃。
请注意，如果文件对象处于只读模式，并且未启用FF_FS_LOCK，则也可以丢弃文件对象，而无需此过程。但是，不建议这样做以备将来兼容。

使用条件

无

f_read - 从文件中读取数据

函数原型

f_read函数从文件中读取数据。

FRESULT f_read (   FIL* fp,     /* [IN] File object */   
                                void* buff,  /* [OUT] Buffer to store read data */   
                                UINT btr,    /* [IN] Number of bytes to read */   
                                UINT* br     /* [OUT] Number of bytes read */ ); 

参数

fp：指向打开的文件对象的指针。
buff：指向缓冲区以存储读取数据的指针。
btr：在 UINT 类型范围内要读取的字节数。如果需要快速读取文件，则应尽可能以大块形式读取该文件。
br：指向接收读取字节数的 UINT 变量的指针。无论函数返回代码如何，此值在函数调用后始终有效。如果返回值等于 btr，则应FR_OK函数返回代码。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_DENIED、FR_INVALID_OBJECT FR_TIMEOUT

描述

该函数开始从读/写指针所指向的文件偏移处读取数据。读/写指针随着读取的字节数而前进。函数成功后，应检查 *br 以检测文件的结尾。如果 *br < btr，则表示读/写指针在读取操作期间命中文件的末尾。

使用条件

无

f_write - 将数据写入文件

函数原型

f_write将数据写入文件。

FRESULT f_write (   FIL* fp,          /* [IN] Pointer to the file object structure */   
                    const void* buff, /* [IN] Pointer to the data to be written */   
                    UINT btw,         /* [IN] Number of bytes to write */   
  UINT* bw   /* [OUT] Pointer to the variable to return number of bytes written */ );

参数

fp:指向打开的文件对象结构的指针。
buff:指向要写入的数据的指针。
btw:指定要写入的 UINT 类型范围内的字节数。如果需要快速写入数据，则应尽可能以大块写入。
bw:指向接收写入的字节数的 UINT 变量的指针。无论函数返回代码如何，此值在函数调用后始终有效。如果返回值等于 btw，则应FR_OK函数返回代码。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_DENIED、FR_INVALID_OBJECT FR_TIMEOUT

描述

该函数开始在读/写指针所指向的文件偏移处向文件写入数据。读/写指针随着写入的字节数而前进。函数成功后，应检查 *bw 以检测磁盘已满。在 *bw < btw 的情况下，这意味着在写入操作期间音量已满。当音量已满或接近满时，该功能可能需要一段时间。

使用条件

当FF_FS_READONLY == 0 时可用。

f_lseek - 移动读/写指针，扩展大小

函数原型

f_lseek函数移动打开的文件对象的文件读/写指针。它还可用于扩展文件大小（群集预分配）。

FRESULT f_lseek (   FIL*    fp,  /* [IN] File object */   
                    FSIZE_t ofs  /* [IN] Offset of file read/write pointer to be set */ ); 

参数

fp:指向打开的文件对象的指针。
ofs:距文件顶部的字节偏移量，用于设置读/写指针。数据类型FSIZE_t是 DWORD（32 位）或 QWORD（64 位）的别名，具体取决于 FF_FS_EXFAT配置选项。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_INVALID_OBJECT、FR_TIMEOUT

描述

打开的文件对象中的文件读/写庞特指向下一次读/写操作时要读/写的数据字节。它随着读取/写入的字节数而前进。f_lseek函数将文件读/写指针移动到文件，而不进行任何读/写操作。f_rewind函数被赋予为宏。
#define f_rewind(fp) f_lseek((fp), 0) 如果在写入模式下指定了超出文件大小的偏移量，则文件大小将扩展到指定的偏移量。展开部分中的文件数据未定义，因为在此过程中不会向文件写入任何数据。这适用于快速将数据区域预分配给文件，以实现快速写入操作。当需要为文件分配连续数据区域时，请改用f_expand函数。f_lseek函数成功后，应检查当前的读/写指针，以确保读/写指针已正确移动。如果读/写指针未指向预期的偏移量，则表示发生了以下任一情况。
● 文件结尾。指定的 ofs 在只读模式下在文件末尾被剪切。
● 磁盘已满。卷上没有可用空间来扩展文件。
快速寻道功能通过使用内存上的 CLMT（群集链路映射表）实现快速向后/长寻道操作，而无需 FAT 访问。它也适用于f_read和f_write功能，但是，当文件处于快速搜索模式时，文件大小不能通过f_write扩展，f_lseek功能。
当 FF_USE_FASTSEEK = 1 时，快速寻道模式可用。在使用快速寻道模式之前，必须将 CLMT 创建到 DWORD 数组中。要创建 CLMT，请将 DWORD 数组的地址设置为打开的文件对象中的成员 cltbl，将数组的大小（以项为单位）设置为 cltbl[0]，然后调用f_lseek函数，其中 ofs = CREATE_LINKMAP。函数成功后，后续f_read不会发生 FAT 访问，f_write f_lseek函数对文件。使用或需要的项目数将返回到 cltbl[0] 中。所需的项目数为（文件片段数 + 1） * 2。例如，数组中的 12 个项目将用于分 5 个部分碎片的文件。如果函数因FR_NOT_ENOUGH_CORE而失败，则给定数组的大小对于该文件而言是不够的。

使用条件

当FF_FS_MINIMIZE< = 2 时可用。要使用快速寻道功能，需要将FF_USE_FASTSEEK设置为 1 才能启用此功能。

f_mkdir - 创建文件夹

f_mkdir-函数创建一个新目录

FRESULT f_mkdir (   const TCHAR* path /* [IN] Directory name */ ); 

参数

路径指向指定要创建的目录名称的空终止字符串的指针。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_NOT_READY、FR_NO_PATH、FR_INVALID_NAME、FR_DENIED、FR_EXIST、FR_WRITE_PROTECTED、FR_INVALID_DRIVE、FR_NOT_ENABLED、FR_NO_FILESYSTEM、FR_TIMEOUT、FR_NOT_ENOUGH_CORE

描述

此函数创建一个新目录。要删除目录，请使用f_unlink函数。

---

f_chdir - 更改逻辑驱动器的当前目录。

FRESULT f_chdir (   const TCHAR* path /* [IN] Path name */ ); 

参数

路径指向以 null 结尾的字符串的指针，该字符串指定要设置为当前目录的目录。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_NOT_READY、FR_NO_PATH、FR_INVALID_NAME、FR_INVALID_DRIVE、FR_NOT_ENABLED、FR_NO_FILESYSTEM、FR_TIMEOUT、FR_NOT_ENOUGH_CORE

描述

f_chdir函数更改逻辑驱动器的当前目录。此外，当前驱动器将在 Unix 样式驱动器前缀时更改，FF_STR_VOLUME_ID == 2。每个逻辑驱动器的当前目录在装载时初始化为根目录。
请注意，当前目录保留在每个文件系统对象中，当前驱动器保留在静态变量中，因此它还会影响使用文件函数的其他任务。

使用条件

当 FF_FS_RPATH >= 1 时可用。

f_unlink - 删除文件或子目录

FRESULT f_unlink (   const TCHAR* path  /* [IN] Object name */ ); 

参数

path：指向以 null 结尾的字符串的指针，该字符串指定要删除的文件或子目录。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_NOT_READY、FR_NO_FILE、FR_NO_PATH、FR_INVALID_NAME、FR_DENIED、FR_WRITE_PROTECTED、FR_INVALID_DRIVE、FR_NOT_ENABLED、FR_NO_FILESYSTEM、FR_TIMEOUT、FR_LOCKED、FR_NOT_ENOUGH_CORE

描述

如果要删除的对象的条件适用于以下条款，则该函数将被拒绝。
● 文件/子目录不得具有只读属性 （AM_RDO），否则该函数将被拒绝并FR_DENIED。
● 子目录必须为空且不能为当前目录，否则该函数将被拒绝并FR_DENIED。
● 文件/子目录不得打开，否则 FAT 卷可以折叠。启用文件锁定功能后，它将被安全拒绝。

使用条件

当FF_FS_READONLY == 0 且 FF_FS_MINIMIZE == 0 时可用。

f_utime - 更改文件或子目录的时间戳

FRESULT f_utime (   
                                const TCHAR* path,  /* [IN] Object name */
                                const FILINFO* fno  /* [IN] Time and data to be set */ ); 

参数

path：指向指定要更改的对象的空终止字符串的指针（文件夹及文件的名字）。
fno：指向具有要在成员 fdate 和 ftime 中设置的时间戳的文件信息结构的指针。

返回值

FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_NOT_READY、FR_NO_FILE、FR_NO_PATH、FR_INVALID_NAME、FR_WRITE_PROTECTED、FR_INVALID_DRIVE、FR_NOT_ENABLED、FR_NO_FILESYSTEM、FR_TIMEOUT、FR_NOT_ENOUGH_CORE