fatfs API使用手册

配置

/*---------------------------------------------------------------------------/
/  Configurations of FatFs Module
/---------------------------------------------------------------------------*/#define FFCONF_DEF	80286	/* Revision ID *//*---------------------------------------------------------------------------/
/ Function Configurations
/---------------------------------------------------------------------------*/#define FF_FS_READONLY	0
/* 此选项可切换只读配置。（0：读/写或1：只读）只读配置删除写入API函数、f_write（）、f_sync（）、，
f_unlink（）、f_mkdir（）、f-chmod（）、f.rename（）、fctruncate（）、fgetfree（）以及可选的写入功能。 */#define FF_FS_MINIMIZE	0
/* 该选项定义了最小化级别以删除一些基本API函数，
0	所有基本API函数都可用。
1	删除F_stat、f_getfree、f_unlink、f_mkdir、f_chmod、f_utime、f_truncate和f_rename函数
2	除1外，F_opendir, f_readdir和f_closedir函数被删除。
3	除2外，F_lseek函数被删除。 */#define FF_USE_FIND		0
/* 禁用(0)或启用(1) 过滤目录读取函数，f_findfirst和f_findnext。此外，ff_fs_minimal需要为0或1 */#define FF_USE_MKFS		0
/* 禁用 (0)或启用 (1) f_mkfs函数*/#define FF_USE_FASTSEEK	0
/* Disable(0)或Enable (1) fast seek function用于**开启f_lseek, f_read和f_write函数的加速模式***/#define FF_USE_EXPAND	0
/* 禁用 (0)或启用 (1)  f_expand函数 */#define FF_USE_CHMOD	0
/* 禁用(0)或启用(1)元数据控制功能f_chmod和f_utime。另外，FF_FS_READONLY需要为0 */#define FF_USE_LABEL	0
/* 禁用 (0) 或启用 (1) 卷标、f_getlabel 和 f_setlabel 的 API 函数 */#define FF_USE_FORWARD	0
/* 禁用 (0) 或启用 (1) f_forward 功能 */#define FF_USE_STRFUNC	0		//项切换字符串函数f_gets、f_putc、f_puts 和 f_printf
#define FF_PRINT_LLI	1		//此选项切换对 f_printf 中 **long long integer 参数的**支持
#define FF_PRINT_FLOAT	1		//此选项切换对 f_printf 中**浮点参数的支持**。 启用此功能时，C 标准需要为 C99 或更高版本，并且 math.h 包含在 ff.c 中。
#define FF_STRF_ENCODE	3
/* FF_USE_STRFUNC switches string functions, f_gets(), f_putc(), f_puts() and
/  f_printf().0	禁用字符串函数
1	启用无需 LF-CRLF 转换的字符串函数
2	使用 LF-CRLF 转换启用字符串函数FF_STRF_ENCODE
值	文件上的字符编码
0	当前代码页中 A使用 ANSI/OEM
1	UTF-16LE 中的 Unicode
2	UTF-16BE 中的 Unicode
3	UTF-8 中的 UnicodeFF_PRINT_FLOAT
值	描述
0	禁用浮点参数
1	在类型“f”、“e”和“E”中启用浮点参数
2	使用小数分隔符“,”而不是“.”
*//*---------------------------------------------------------------------------/
/ Locale and Namespace Configurations
本地和命名空间的配置
/---------------------------------------------------------------------------*/#define FF_CODE_PAGE	437
/*指定目标系统上使用的 OEM 代码页值	代码页
0	包括以下所有代码页并由 f_setcp() 设置
437	美国
720	阿拉伯
737	希腊
771	KBL
775	波罗的海
850	拉丁语 1
852	拉丁语 2
855	西里尔
857	土耳其
860	葡萄牙
861	冰岛
862	希伯来
863	加拿大法语
864	阿拉伯
865	北欧
868	俄罗斯
869	希腊语 2
932	日语 (DBCS)
936	简体中文 (DBCS)
949	韩语 (DBCS)
950	繁体中文 (DBCS)
*/#define FF_USE_LFN		0 //长文件名 (LFN) 的支持
#define FF_MAX_LFN		255
/* The FF_USE_LFN switches the support for LFN (long file name).0	禁用 LFN。 只能使用 8.3 格式的路径名
1	在 BSS 上使用静态工作缓冲区启用 LFN。 始终不是线程安全的
2	在 STACK 上使用动态工作缓冲区启用 LFN
3	在 HEAP 上使用动态工作缓冲区启用 LFN
/
启用 LFN 时，需要将 Unicode 支持模块 ffunicode.c 添加到项目中。 当使用堆栈作为工作缓冲区时，请注意堆栈溢出。 当工作缓冲区使用堆内存时，需要在项目中添加内存管理函数（ff_memalloc和ff_memfree）*/#define FF_LFN_UNICODE	0
/* 当长文件名使能时指定一种编码.
值	字符编码	TCHAR
0	当前 CP 中的 ANSI/OEM	char
1	UTF-16 中的 Unicode	WCHAR
2	UTF-8 中的 Unicode	char
3	UTF-32 中的 Unicode	DWORD
/
/  Also behavior of string I/O functions will be affected by this option.
/  When LFN is not enabled, this option has no effect. */#define FF_LFN_BUF		255
#define FF_SFN_BUF		12
/* This set of options defines size of file name members in the FILINFO structure
/  which is used to read out directory items. These values should be suffcient for
/  the file names to read. The maximum possible length of the read file name depends
/  on character encoding. When LFN is not enabled, these options have no effect. */#define FF_FS_RPATH		0
/* 配置相对路径功能.
0	禁用相对路径并删除相关功能。
1	启用相对路径。 f_chdir 和 f_chdrive 函数可用。
2	f_getcwd 函数除 1 外还可用
容器卷/驱动配置
*//*---------------------------------------------------------------------------/
/ Drive/Volume Configurations
/---------------------------------------------------------------------------*/#define FF_VOLUMES		1
/*此选项**配置要使用的卷数**（最多 10 个逻辑驱动器） */#define FF_STR_VOLUME_ID	0
/*
此选项切换对字符串卷 ID 的支持。 当为驱动器前缀启用卷 ID 的任意字符串时，FF_VOLUME_STRS 预定义的字符串或用户定义的字符串也可以用作路径名中的驱动器前缀。 
无论此选项如何，数字驱动器编号始终有效，并且可以通过此选项启用驱动器前缀的任一格式const char* VolumeStr[FF_VOLUMES] = {"ram","flash","sd","usb",...
值	描述	示例
0	只能使用数字 ID 中的 DOS/Windows 风格驱动器前缀。		1:/filename
1	也可以使用字符串 ID 中的 DOS/Windows 风格驱动器前缀。	flash:/filename
2	也可以使用字符串 ID 中的 Unix 风格驱动器前缀			/flash/filename
*/
#define FF_VOLUME_STRS		"RAM","NAND","CF","SD","SD2","USB","USB2","USB3"
/* 此选项定义每个逻辑驱动器的卷 ID 字符串.项目数不得少于 FF_VOLUMES。 卷 ID 字符串的有效字符是 A-Z、a-z 和 0-9，但是，它们在比较时不区分大小写。 如果 FF_STR_VOLUME_ID == 0，则此选项无效
如FF_STR_VOLUME_ID >= 1 且未定义此选项，则需要定义用户定义的卷字符串表，如下所示。 该表不应即时修改。/* 用户定义的卷 ID 字符串 0: 到 3: 
const char* VolumeStr[FF_VOLUMES] = {"ram","flash","sd","usb"};. 
*/#define FF_MULTI_PARTITION	0
/*
禁用 (0) 或启用 (1)。 该选项切换**多分区功能**。 默认情况下 (0)，每个逻辑驱动器号都绑定到相同的物理驱动器号，并且只装载物理驱动器中的一个卷。 启用后，每个逻辑驱动器都绑定到用户定义的分区解析表 VolToPart[] 中列出的物理驱动器上的分区。
*/#define FF_MIN_SS		512
#define FF_MAX_SS		512
/* 这组选项定义了用于低级磁盘 I/O 接口、**disk_read 和 disk_write 函数的扇区大小范围**，有效值为 512、1024、2048 和 4096。
FF_MIN_SS 定义最小扇区大小，FF_MAX_SS 定义最大扇区大小。 始终为存储卡和硬盘设置 512。 但板载闪存和某些类型的光学介质可能需要更大的值。 
当 FF_MAX_SS > FF_MIN_SS 时，启用可变扇区大小的支持，需要对 disk_ioctl 函数执行 GET_SECTOR_SIZE 命令 */#define FF_LBA64		0
/*此选项将媒体访问接口切换到 64 位 LBA，并启用用于分区管理的 GUID 分区表 (GPT)，启用 (1) 或禁用 (0)。 需要启用 exFAT 文件系统才能启用此功能*/#define FF_MIN_GPT		0x10000000
/*此选项指定在 f_mkfs 和 f_fdisk 函数中在驱动器上创建分区时**确定分区格式的阈值**。 当可用扇区数等于或大于此值时，驱动器将按 GPT 分区。 当 FF_LBA64 == 0 时，此选项无效 */#define FF_USE_TRIM		0
/* 禁用 (0) 或启用 (1)。 此选项切换 ATA-TRIM 功能。 要启用 Trim 功能，还应该对 disk_ioctl 功能执行 CTRL_TRIM 命令. *//*---------------------------------------------------------------------------/
/ System Configurations
/---------------------------------------------------------------------------*/#define FF_FS_TINY		0
/*正常 (0) 或微型 (1)。 微型配置减少了 FIL 结构、文件对象、FF_MAX_SS 字节的大小。 FATFS 结构中的公共扇区缓冲区、文件系统对象用于文件数据传输，而不是从文件对象中消除私有扇区缓冲区。 */#define FF_FS_EXFAT		0
/* 
除了 FAT/FAT32 文件系统之外，此选项还会切换对 exFAT 文件系统的支持，启用 (1) 或禁用 (0)。 
要启用 exFAT，还必须启用 LFN，建议配置 FF_LFN_UNICODE >= 1 和 FF_MAX_LFN == 255 以获得全功能的 exFAT 功能。 
*/#define FF_FS_NORTC		0	
/*
使用 RTC (0) 或不使用 RTC (1) 。将 FF_FS_NORTC 设置为 1 以禁用时间戳功能。 
FatFs 修改的每个对象都将有一个由 FF_NORTC_MON、FF_NORTC_MDAY 和 FF_NORTC_YEAR 定义的常量时间戳。
要使用时间戳功能，请设置 FF_FS_NORTC == 0 并将 get_fattime 函数添加到项目以从 RTC 获取当前时间。 此选项对只读配置没有影响
*/#define FF_NORTC_MON	1
#define FF_NORTC_MDAY	1
#define FF_NORTC_YEAR	2022
/* 这组选项定义了在无 RTC 系统中使用的时间。 此选项对只读配置或 FF_FS_NORTC == 0 没有影响 */#define FF_FS_NOFSINFO	0
/* 
0 到 3。如果您需要知道 FAT32 卷上的正确可用空间，请设置此选项的位 0，并且在卷安装后的第一次 f_getfree 函数将强制进行完整的 FAT 扫描。 位 1 控制使用最后分配的簇号进行新分配。值	描述
bit0=0	如果可用，请使用 FSINFO 中的空闲簇计数。
bit0=1	不要相信 FSINFO 中的空闲簇计数。
bit1=0	使用 FSINFO 中最后分配的簇号来查找空闲簇（如果可用）
bit1=0	不要相信 FSINFO 中最后分配的簇号。
*/#define FF_FS_LOCK		0
/* 该选项切换文件锁定功能以控制重复文件打开和对打开对象的非法操作。 请注意，此功能与重新进入无关。 此选项在只读配置中必须为 0。值	描述
0	禁用文件锁定功能。 为避免错误的文件操作导致文件崩溃，应用程序需要避免非法打开、删除和重命名打开的对象
1	启用文件锁定功能。 该值定义了在文件锁定功能下可以同时打开多少个文件/子目录。 对打开对象的非法操作将被 FR_LOCKED 拒绝
*/
#define FF_FS_REENTRANT	0/*
禁用 (0) 或启用 (1)。 此选项切换 FatFs 模块本身的重入（线程安全）。 
请注意，对不同卷的文件/目录访问始终是可重入的，并且无论此选项如何，它都可以同时工作，但是，卷管理功能 f_mount、f_mkfs 和 f_fdisk 始终不可重入。 
此功能仅控制对同一卷的文件/目录访问，换句话说，对每个文件系统对象的独占使用。 
要启用此功能，还需要将用户提供的同步处理程序 ff_mutex_take、ff_mutex_give、ff_mutex_create 和 ff_mutex_delete 添加到项目中。 
ffsystem.c 中提供了示例代码。
*/
#define FF_FS_TIMEOUT	1000
/*
当等待时间超过此时间段时，使用 FR_TIMEOUT 中止文件功能的 O/S 时间滴答数。 当 FF_FS_REENTRANT == 0 时，此选项无效。
*//*--- End of configuration options ---*/

FS的返回码

大多数API函数以枚举类型FRESULT返回常见的结果代码。当API函数成功时，它返回零（FR_OK），否则返回非零值表示错误类型。

FR_OK（成功）,
FR_DISK_ERR（下层disk_read、disk_write或disk_ioctl函数报告发生了不可恢复的硬盘错误。）,
FR_INT_ERR（断言失败，在内部流程中检测到异常）,
FR_NOT_READY（下层disk_initialize函数报告存储设备无法做好工作准备。）,
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（f_mount函数尚未注册逻辑驱动器的工作区域。没挂载）,
FR_NO_FILESYSTEM,（在驱动器中找不到有效的FAT卷。）
FR_MKFS_ABORTED（f_mkfs函数在格式化启动前中止）,
FR_TIMEOUT（由于线程安全控制超时，该函数被取消。（）,
FR_LOCKED（对对象的操作被文件共享控制拒绝）,
FR_NOT_ENOUGH_CORE（内存不足，无法进行操作。）
FR_TOO_MANY_OPEN_FILES（打开的对象数已达到最大值，无法再打开任何对象。）
FR_INVALID_PARAMETER（给定的参数无效，或者卷存在不一致的参数。）

API

1.f_mount注册/注销一个工作区

在FatFs模块上注册/注销一个工作区(文件系统对象)

FRESULT f_mount ( BYTE Drive, FATFS* FileSystemObject );

参数	说明
Drive	注册/注销工作区的逻辑驱动器号(0-9)
FileSystemObject	工作区(文件系统对象)指针
返回值	FR_OK (0)：函数成功。 FR_INVALID_DRIVE：驱动器号无效

• f_mount函数在FatFs模块上注册/注销一个工作区。在使用任何其他文件函数之前，必须使用该函数为每个卷注册一个工作区
• 注销一个工作区，只要指定FileSystemObject为NULL即可，然后该工作区可以被丢弃。该函数只初始化给定的工作区，以及将该工作区的地址注册到内部表中，不访问磁盘I/O层

2.f_open创建/打开文件对象

如果函数成功，则创建一个文件对象。该文件对象被后续的读/写函数用来访问文件。如果想要关闭一个打开的文件对象，则使用f_close函数。如果不关闭修改后的文件，那么文件可能会崩溃。在使用任何文件函数之前，必须使用f_mount函数为驱动器注册一个工作区。只有这样，其他文件函数才能正常工作

FRESULT f_open ( FIL* FileObject, const XCHAR* FileName,BYTE ModeFlags );

参数	说明
FileObject	将被创建的文件对象结构的指针
FileName	NULL结尾的字符串指针，该字符串指定了将被创建或打开的文件名
ModeFlags	指定文件的访问类型和打开方法。它是由下列标志的一个组合指定的
返回值	FR_OK (0)：函数成功，该文件对象有效。 FR_NO_FILE：找不到该文件。 FR_NO_PATH：找不到该路径。 FR_INVALID_NAME：文件名无效。 FR_INVALID_DRIVE：驱动器号无效。 FR_EXIST：该文件已存在。 FR_DENIED：由于下列原因，所需的访问被拒绝： （1）以写模式打开一个只读文件。 （2）由于存在一个同名的只读文件或目录，而导致文件无法被创建。 （3）由于目录表或磁盘已满，而导致文件无法被创建。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_WRITE_PROTECTED：在存储介质被写保护的情况下，以写模式打开或创建文件对象。 FR_DISK_ERR：由于底层磁盘I/O接口函数中的一个错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_ENABLED：逻辑驱动器没有工作区。 FR_NO_FILESYSTEM：磁盘上没有有效地FAT卷

参数	说明
#define FA_READ 0x01	读文件
#define FA_WRITE 0x02	写文件
#define FA_OPEN_EXISTING 0x00	打开一个已经存在的文件，没有打开失败
#define FA_CREATE_NEW 0x04	如果有文件则打开，否则创建一个文件
#define FA_CREATE_ALWAYS 0x08	创建一个文件，如果有则创建失败
#define FA_OPEN_ALWAYS 0x10	创建一个新文件，如果文件存在则将会被截断并覆盖
#define FA_OPEN_APPEND 0x30	追加的方式打开文件

3.f_close关闭一个打开的文件

描述：f_close函数关闭一个打开的文件对象。无论向文件写入任何数据，文件的缓存信息都将被写回到磁盘。该函数成功后，文件对象不再有效，并且可以被丢弃。如果文件对象是在只读模式下打开的，不需要使用该函数，也能被丢弃

FRESULT f_close ( FIL* FileObject );

参数	说明
FileObject	指向将被关闭的已打开的文件对象结构的指针
返回值	FR_OK (0) 文件对象已被成功关闭。 FR_DISK_ERR 由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT：文件对象无效

4.f_read从一个文件读取数据

描述:文件对象中的读/写指针增加已读取字节数。该函数成功后，应该检查 *ByteRead 来检测文件是否结束。在读操作过程中，一旦 *ByteRead < ByteToRead ，则读/写指针到达了文件结束位置。

FRESULT f_read ( FIL* FileObject, void* Buffer, UINT ByteToRead, UINT* ByteRead );

参数	说明
FileObject	指向将被读取的已打开的文件对象结构的指针。
Buffer	指向存储读取数据的缓冲区的指针。首先要定义一个至少512的内存
ByteToRead	要读取的字节数，UINT范围内。
ByteRead	指向返回已读取字节数的UINT变量的指针。在调用该函数后，无论结果如何，数值都是有效的。
返回值	FR_OK (0):函数成功。 FR_DENIED:由于文件是以非读模式打开的，而导致该函数被拒绝。 FR_DISK_ERR:由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR:由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY:由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT: 文件对象无效。

5.f_write写入数据到一个文件

描述：文件对象中的读/写指针以已写入字节数增加。该函数成功后，应该检查 *ByteWritten 来检测磁盘是否已满。在写操作过程中，一旦 *ByteWritten < *ByteToWritten ，则意味着该卷已满

f_write ( FIL* FileObject, const void* Buffer, UINT ByteToWrite,UINT* ByteWritten );

参数	说明
FileObject	指向将被读取的已打开的文件对象结构的指针。
Buffer	指向存储待写入数据的缓冲区的指针
ByteToWrite	要写入的字节数，UINT范围内。
ByteWritten	指向返回已写入字节数的UINT变量的指针。在调用该函数后，无论结果如何，数值都是有效的。
返回值	FR_OK (0)：函数成功。 FR_DENIED：由于文件是以非写模式打开的，而导致该函数被拒绝。 FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT 文件对象无效。

6.f_lseek移动指针。

也可以被用来扩展文件大小(簇预分配)。

描述：f_lseek函数当FS_MINIMIZE <= 2时可用。offset只能被指定为相对于文件起始处的字节数。当在写模式下指定了一个超过文件大小的offset时，文件的大小将被扩展，并且该扩展的区域中的数据是未定义的。这适用于为快速写操作迅速地创建一个大的文件。f_lseek函数成功后，为了确保读/写指针已被正确地移动，必须检查文件对象中的成员fptr。如果fptr不是所期望的值，则发生了下列情况之一。

（1）文件结束。指定的offset被钳在文件大小，因为文件已被以只读模式打开。

（2）磁盘满。卷上没有足够的空闲空间去扩展文件大小。

用法：其实这个函数可以解决文件从头开始读的问题，如果你想打开一个文件，读取里面的内容，但又不想从头开始读，那么你可以使用这个函数来解决

FRESULT f_lseek ( FIL* FileObject, DWORD Offset );

参数	说明
FileObject	指向将被关闭的已打开的文件对象结构的指针
Offset	相对于文件起始处的字节数
返回值	FR_OK (0)：函数成功。 FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT：文件对象无效。

7.f_truncate截断文件大小

描述：f_truncate函数当_FS_READONLY == 0 并且 _FS_MINIMIZE == 0时可用。f_truncate函数截断文件到当前的文件读/写指针。当文件读/写指针已经指向文件结束时，该函数不起作用

FRESULT f_truncate ( FIL* FileObject );

参数	说明
FileObject	待截断的打开的文件对象的指针
返回值	FR_OK (0)：函数成功。 FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT 文件对象无效

8.f_sync冲洗一个写文件的缓存信息

描述：f_sync函数当_FS_READONLY == 0时可用。f_sync函数和f_close函数执行同样的过程，但是文件仍处于打开状态，并且可以继续对文件执行读/写/移动指针操作。这适用于以写模式长时间打开文件，比如数据记录器。定期的或f_write后立即执行f_sync可以将由于突然断电或移去磁盘而导致数据丢失的风险最小化。在f_close前立即执行f_sync没有作用，因为在f_close中执行了f_sync。换句话说，这两个函数的差异就是文件对象是不是无效的

FRESULT f_sync ( FIL* FileObject );

参数	说明
FileObject	待冲洗的打开的文件对象的指针
返回值	FR_OK (0)：函数成功。 FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_INVALID_OBJECT 文件对象无效

9.f_opendir打开一个目录

f_opendir函数当_FS_MINIMIZE <= 1时可用。f_opendir函数打开一个已存在的目录，并为后续的调用创建一个目录对象。该目录对象结构可以在任何时候不经任何步骤而被丢弃

FRESULT f_opendir ( DIR* DirObject, const XCHAR* DirName );

参数	说明
DirObject	待创建的空白目录对象的指针
DirName	'\0’结尾的字符串指针，该字符串指定了将被打开的目录名。
返回值	FR_OK (0)：函数成功，目录对象被创建。该目录对象被后续调用，用来读取目录项。 FR_NO_PATH：找不到路径。 FR_INVALID_NAME：路径名无效。 FR_INVALID_DRIVE：驱动器号无效。 FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。 FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。 FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。 FR_NOT_ENABLED：逻辑驱动器没有工作区。 FR_NO_FILESYSTEM：磁盘上没有有效的FAT卷。

10.f_unlink - 删除文件或子目录

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

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

11.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 中设置的时间戳的文件信息结构的指针

12.f_gets - 从文件中读取一个字符串

描述
读取操作将继续，直到存储“\n”、到达文件末尾或缓冲区充满 len - 1 个字符。 读取的字符串以“\0”结尾。 当没有字符可读取或读取操作发生任何错误时，它返回一个空指针。 可以使用 f_eof 和 f_error 函数检查 EOF 和错误的状态。

TCHAR* f_gets (TCHAR* buff, /* [OUT] 指向读取缓冲区的指针，用于存储读取的字符串。 */int len,     /* [IN] 以项目为单位的读取缓冲区的大小。 */FIL* fp      /* [IN] 指向打开文件对象结构的指针。 */
);/* 读取每一行并显示出来 */while (f_gets(line, sizeof line, &fil)) {printf(line);}

13.f_putc - 将一个字符放入文件

int f_putc (TCHAR chr,  /* [IN] 要写的字符 */FIL* fp     /* [IN] 指向打开文件对象结构的指针 */
);

14.f_puts - 将字符串写入文件

int f_puts (const TCHAR* str, /* [IN] 指向要写入的空终止字符串的指针。 不会写入终止符 */FIL* fp           /* [IN] 指向打开文件对象结构的指针 */
);

15.f_printf - 将格式化字符串写入文件

int f_printf (FIL* fp,          /* [IN] 指向打开文件对象结构的指针 */const TCHAR* fmt, /* [IN] 指向空的 '\0' 终止格式字符串的指针。 不会输出终止符。*/...               /*Optional arguments...*/
);
f_printf(fp, "%d", 1234);             /* "1234" */

描述
格式控制指令是标准库的一个子集，如下所示：

%[flag][width][precision][size]type

flag

填充选项。 A - 指定左对齐。 0 指定零填充。 默认设置是右对齐和空格填充。

width

字段的最小宽度，1-99 或 *。 如果生成的字符串的宽度小于最小宽度，则剩余字段用空格或零填充。 * 指定值来自 int 类型的参数。 默认设置为零。

precision

指定小数位数或字符串的最大宽度，.0-.99 或 .*。 如果省略数字，则与 .0 相同。 默认设置为数字 6，字符串无限制。

size

指定整数参数 l(long) 和 ll(long long) 的大小。 如果 sizeof (long) == sizeof (int) 为真（这是典型的 32 位系统），则可以省略长整型参数的前缀 l。 整数参数的默认大小为 int，浮点参数始终假定为 double 作为默认参数提升。

type

f_printf的返回： 当字符串写入成功时，它返回写入文件的字符编码单元数。 当函数因磁盘已满或错误而失败时，将返回一个负值。

16.f_tell - 获取文件的当前读/写指针

此功能作为宏实现

#define f_tell(fp) ((fp)->fptr)

17.f_eof - 测试文件的文件结尾

此功能作为宏实现

#define f_eof(fp) ((int)((fp)->fptr == (fp)->fsize))

18.f_size - 获取文件的大小

作为宏实现

#define f_size(fp) ((fp)->obj.objsize)

19.f_getfree获取空闲簇的数目

FRESULT f_getfree ( const XCHAR* Path,       /*  驱动器的根目录  */ DWORD* Clusters,         /*  存储空闲簇数目变量的指针  */ FATFS** FileSystemObject /*  文件系统对象指针的指针  */ 
); 

参数

Path ;‘\0’ 结尾的字符串指针，该字符串指定了逻辑驱动器的目录。

Clusters ;存储空闲簇数目的 DWORD 变量的指针。

FileSystemObject ;相应文件系统对象指针的指针。

---

其他API

名称 简介
f_open 打开/创建文件
f_close 关闭已打开的文件
f_read 从文件中读取数据
f_write 将数据写入文件
f_lseek 移动读/写指针，扩展大小
f_truncate 截断文件大小
f_sync 刷新缓存数据
f_forward 为数据转发到流
f_expand 为文件分配连续的块
f_gets 读取字符串
f_putc 写一个字符
f_puts 编写字符串
f_printf 编写格式化字符串
f_tell 获取当前读/写指针
f_eof 文件结尾测试
f_size 获取大小
f_error 测试错误
2️⃣ 目录访问
名称 简介
f_opendir 打开目录
f_closedir 关闭打开的目录
f_readdir 读取目录项
f_findfirst 打开目录并读取匹配的第一个项目
f_findnext 读取下一个匹配的项目
3️⃣ 文件和目录管理
名称 简介
f_stat 检查文件或子目录是否存在
f_unlink 删除文件或子目录
f_rename 重命名/移动文件或子目录
f_chmod 更改文件或子目录的属性
f_utime 更改文件或子目录的时间戳
f_mkdir 创建子目录
f_chdir 更改当前目录
f_chdrive 更改当前驱动器
f_getcwd 检索当前目录和驱动器

4️⃣ 卷管理和系统配置
名称 简介
f_mount 注册/注销卷的工作区域
f_mkfs 在逻辑驱动器上创建 FAT 卷
f_fdisk 在物理驱动器上创建分区
f_getfree 获取卷上的可用空间
f_getlabel 获取卷标
f_setlabel 设置卷标
f_setcp 设置活动代码页

---

原文链接：https://blog.csdn.net/qq_41650023/article/details/125201954