开发: C++知识库 Java知识库 JavaScript Python PHP知识库人工智能区块链大数据移动开发嵌入式开发工具数据结构与算法开发测试游戏开发网络协议系统运维
教程: HTML教程 CSS教程 JavaScript教程 Go语言教程 JQuery教程 VUE教程 VUE3教程 Bootstrap教程 SQL数据库教程 C语言教程 C++教程 Java教程 Python教程 Python3教程 C#教程
数码: 电脑笔记本显卡显示器固态硬盘硬盘耳机手机 iphone vivo oppo 小米华为单反装机图拉丁

-> 开发工具 -> FatFs 常用 API 详细记录 -> 正文阅读

[开发工具]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 模块，如下所示：

确定由路径指定的逻辑驱动器。
清除和注销卷的注册工作区（如果存在）。
如果 fs 不为 NULL，则清除新工作区并将其注册到卷。
如果指定了强制装入，则对卷执行卷装入过程。
如果逻辑驱动器上有任何打开的文件或目录对象，则该对象将被此函数失效。
如果未指定强制安装（选择 = 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