FatFs 应用接口函数

FS的配置选项

针对每个项目的不同需求，有许多选项可以配置FatFs的功能。配置选项在ffconf.h中定义。

功能设置

FF_FS_READONLY

Read/Write(0)或Read-only (1). Read-only配置删除了写API函数，f_write、f_sync、f_unlink、f_mkdir、f_chmod、f_rename、f_truncate、f_getfree以及可选的写函数。

FF_FS_MINIMIZE

该选项定义了最小化级别以删除一些基本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函数被删除。

FF_USE_FIND

禁用(0)或启用(1) 过滤目录读取函数，f_findfirst和f_findnext。此外，ff_fs_minimal需要为0或1。

FF_USE_MKFS

Disable (0) or Enable (1) f_mkfs函数。

FF_USE_FASTSEEK

Disable(0)或Enable (1) fast seek function用于开启f_lseek, f_read和f_write函数的加速模式。欲了解更多信息，请阅读f_lseek函数。

FF_USE_EXPAND

Disable(0)或Enable (1) f_expand函数。

FF_USE_CHMOD

禁用(0)或启用(1)元数据控制功能f_chmod和f_utime。另外，FF_FS_READONLY需要为0。

FF_USE_LABEL

禁用 (0) 或启用 (1) 卷标、f_getlabel 和 f_setlabel 的 API 函数。

FF_USE_FORWARD

禁用 (0) 或启用 (1) f_forward 功能。

FF_USE_STRFUNC

此选项切换字符串函数、f_gets、f_putc、f_puts 和 f_printf。 这些函数等同于 POSIX 中的常规字符串流 I/O 函数。 如果 sprintf 可用且不需要代码转换，则使用 sprintf 的 f_write 在代码大小和性能方面比 f_printf 更高效。 启用此功能时，stdarg.h 包含在 ff.c 中。

值	描述
0	禁用字符串函数
1	启用无需 LF-CRLF 转换的字符串函数
2	使用 LF-CRLF 转换启用字符串函数

FF_PRINT_LLI

此选项切换对 f_printf 中 long long integer 参数的支持。

禁用 (0) 或启用 (1)。 启用此功能时，C 标准需要为 C99 或更高版本。

FF_PRINT_FLOAT

此选项切换对 f_printf 中浮点参数的支持。 启用此功能时，C 标准需要为 C99 或更高版本，并且 math.h 包含在 ff.c 中。

值	描述
0	禁用浮点参数
1	在类型“f”、“e”和“E”中启用浮点参数
2	使用小数分隔符“,”而不是“.”

FF_STRF_ENCODE

当 API 上的字符编码为 Unicode (FF_LFN_UNICODE >= 1) 时，FF_USE_STRFUNC 启用的字符串 I/O 函数会转换其中的字符编码。 此选项定义要通过这些函数读取/写入的文件的字符编码假设。 当 LFN 未启用或 FF_LFN_UNICODE == 0 时，字符串函数无需任何代码转换即可工作，并且此选项无效。

值	文件上的字符编码
0	当前代码页中 A使用 ANSI/OEM
1	UTF-16LE 中的 Unicode
2	UTF-16BE 中的 Unicode
3	UTF-8 中的 Unicode

名称空间和区域配置

FF_CODE_PAGE

此选项指定目标系统上使用的 OEM 代码页。 代码页设置不正确会导致文件打开失败。 如果任何非 ASCII 字符未用于路径名或 FF_LFN_UNICODE != 0，则任何代码页设置之间没有区别。 无论如何设置它437。

值	代码页
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)

FF_USE_LFN

此选项切换对长文件名 (LFN) 的支持。 启用 LFN 时，需要将 Unicode 支持模块 ffunicode.c 添加到项目中。 当使用堆栈作为工作缓冲区时，请注意堆栈溢出。 当工作缓冲区使用堆内存时，需要在项目中添加内存管理函数（ff_memalloc和ff_memfree）。

值	描述
0	禁用 LFN。 只能使用 8.3 格式的路径名
1	在 BSS 上使用静态工作缓冲区启用 LFN。 始终不是线程安全的
2	在 STACK 上使用动态工作缓冲区启用 LFN
3	在 HEAP 上使用动态工作缓冲区启用 LFN

FF_MAX_LFN

LFN 函数需要一定的内部工作缓冲区来存储文件名。 此选项定义缓冲区的大小，值可以在 LFN 的 12 到 255 个字符（实际上是 UTF-16 代码单元）的范围内。 当启用 exFAT 时，缓冲区占用 (FF_MAX_LFN + 1) * 2 个字节和额外的 (FF_MAX_LFN + 44) / 15 * 32 个字节。 建议设置为 255 以完全支持 LFN 规范。 当未启用 LFN 时，此选项无效。

FF_LFN_UNICODE

此选项切换 API 上文件名的字符编码。 FatFs 最多支持 U+10FFFF 的代码点。 该选项还影响字符串 I/O 函数的行为（参见 FF_STRF_ENCODE）。

值	字符编码	TCHAR
0	当前 CP 中的 ANSI/OEM	char
1	UTF-16 中的 Unicode	WCHAR
2	UTF-8 中的 Unicode	char
3	UTF-32 中的 Unicode	DWORD
选择Unicode时，FF_CODE_PAGE除了兼容遗留系统，如MS-DOS和任何不支持LFN的系统，实际上没有任何意义。

未启用 LFN 时，此选项无效，FatFs 在 API 上以 ANSI/OEM 代码运行。 有关更多信息，请阅读FatFs Module Application Note中的Unicode API。

FF_LFN_BUF, FF_SFN_BUF

这组选项在用于读出目录项的 FILINFO 结构中定义了文件名成员 fname[] 和 altname[] 的大小。 这些值应该足以让文件名读取。 读取文件名的最大可能长度取决于 API 上的字符编码方案，如下所示：

编码	长文件名长度	SFN长度
SBCS 中的 ANSI/OEM	255项	12项
DBCS 中的 ANSI/OEM	510项	12项
UTF-16/32 中的 Unicode	255项	12项
UTF-8 中的 Unicode	765项	34项

如果名称成员的大小对于 LFN 来说不足，则该项目被视为没有 LFN。 未启用 LFN 时，这些选项无效。

FF_FS_RPATH

该选项配置相对路径功能。 有关更多信息，请阅读FatFs Module Application Note中的Format of the Path Names。

值	描述
0	禁用相对路径并删除相关功能。
1	启用相对路径。 f_chdir 和 f_chdrive 函数可用。
2	f_getcwd 函数除 1 外还可用

容器卷/驱动配置

FF_VOLUMES

此选项配置要使用的卷数（最多 10 个逻辑驱动器）。

FF_STR_VOLUME_ID

此选项切换对字符串卷 ID 的支持。 当为驱动器前缀启用卷 ID 的任意字符串时，FF_VOLUME_STRS 预定义的字符串或用户定义的字符串也可以用作路径名中的驱动器前缀。 无论此选项如何，数字驱动器编号始终有效，并且可以通过此选项启用驱动器前缀的任一格式。

值	描述	示例
0	只能使用数字 ID 中的 DOS/Windows 风格驱动器前缀。	1:/filename
1	也可以使用字符串 ID 中的 DOS/Windows 风格驱动器前缀。	flash:/filename
2	也可以使用字符串 ID 中的 Unix 风格驱动器前缀。	/flash/filename

FF_VOLUME_STRS

此选项定义每个逻辑驱动器的卷 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"};

FF_MULTI_PARTITION

禁用 (0) 或启用 (1)。 该选项切换多分区功能。 默认情况下 (0)，每个逻辑驱动器号都绑定到相同的物理驱动器号，并且只装载物理驱动器中的一个卷。 启用后，每个逻辑驱动器都绑定到用户定义的分区解析表 VolToPart[] 中列出的物理驱动器上的分区。 f_fdisk 功能也将可用。 有关更多信息，请阅读FatFs Module Application Note中的Volume Management。

FF_MIN_SS, FF_MAX_SS

这组选项定义了用于低级磁盘 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 命令。

FF_LBA64

此选项将媒体访问接口切换到 64 位 LBA，并启用用于分区管理的 GUID 分区表 (GPT)，启用 (1) 或禁用 (0)。 需要启用 exFAT 文件系统才能启用此功能。

FF_GPT_MIN（FF_MIN_GPT）

此选项指定在 f_mkfs 和 f_fdisk 函数中在驱动器上创建分区时确定分区格式的阈值。 当可用扇区数等于或大于此值时，驱动器将按 GPT 分区。 当 FF_LBA64 == 0 时，此选项无效。

FF_USE_TRIM

禁用 (0) 或启用 (1)。 此选项切换 ATA-TRIM 功能。 要启用 Trim 功能，还应该对 disk_ioctl 功能执行 CTRL_TRIM 命令。

系统设置

FF_FS_TINY

正常 (0) 或微型 (1)。 微型配置减少了 FIL 结构、文件对象、FF_MAX_SS 字节的大小。 FATFS 结构中的公共扇区缓冲区、文件系统对象用于文件数据传输，而不是从文件对象中消除私有扇区缓冲区。

FF_FS_EXFAT

除了 FAT/FAT32 文件系统之外，此选项还会切换对 exFAT 文件系统的支持，启用 (1) 或禁用 (0)。 要启用 exFAT，还必须启用 LFN，建议配置 FF_LFN_UNICODE >= 1 和 FF_MAX_LFN == 255 以获得全功能的 exFAT 功能。 请注意，启用 exFAT 会放弃 ANSI C (C89) 兼容性并需要 C99，因为需要 64 位整数类型。

FF_FS_NORTC

使用 RTC (0) 或不使用 RTC (1)。 此选项控制时间戳特征。 如果系统没有 RTC 或不需要有效的时间戳，将 FF_FS_NORTC 设置为 1 以禁用时间戳功能。 FatFs 修改的每个对象都将有一个由 FF_NORTC_MON、FF_NORTC_MDAY 和 FF_NORTC_YEAR 定义的常量时间戳。 要使用时间戳功能，请设置 FF_FS_NORTC == 0 并将 get_fattime 函数添加到项目以从 RTC 获取当前时间。 此选项对只读配置没有影响。

FF_NORTC_MON, FF_NORTC_MDAY, FF_NORTC_YEAR

这组选项定义了在无 RTC 系统中使用的时间。 此选项对只读配置或 FF_FS_NORTC == 0 没有影响。

FF_FS_NOFSINFO

0 到 3。如果您需要知道 FAT32 卷上的正确可用空间，请设置此选项的位 0，并且在卷安装后的第一次 f_getfree 函数将强制进行完整的 FAT 扫描。 位 1 控制使用最后分配的簇号进行新分配。

值	描述
bit0=0	如果可用，请使用 FSINFO 中的空闲簇计数。
bit0=1	不要相信 FSINFO 中的空闲簇计数。
bit1=0	使用 FSINFO 中最后分配的簇号来查找空闲簇（如果可用）
bit1=0	不要相信 FSINFO 中最后分配的簇号。

FF_FS_LOCK

该选项切换文件锁定功能以控制重复文件打开和对打开对象的非法操作。 请注意，此功能与重新进入无关。 此选项在只读配置中必须为 0。

值	描述
0	禁用文件锁定功能。 为避免错误的文件操作导致文件崩溃，应用程序需要避免非法打开、删除和重命名打开的对象
>0	启用文件锁定功能。 该值定义了在文件锁定功能下可以同时打开多少个文件/子目录。 对打开对象的非法操作将被 FR_LOCKED 拒绝

FF_FS_REENTRANT

禁用 (0) 或启用 (1)。 此选项切换 FatFs 模块本身的重入（线程安全）。 请注意，对不同卷的文件/目录访问始终是可重入的，并且无论此选项如何，它都可以同时工作，但是，卷管理功能 f_mount、f_mkfs 和 f_fdisk 始终不可重入。 此功能仅控制对同一卷的文件/目录访问，换句话说，对每个文件系统对象的独占使用。 要启用此功能，还需要将用户提供的同步处理程序 ff_mutex_take、ff_mutex_give、ff_mutex_create 和 ff_mutex_delete 添加到项目中。 ffsystem.c 中提供了示例代码。

FF_FS_TIMEOUT

当等待时间超过此时间段时，使用 FR_TIMEOUT 中止文件功能的 O/S 时间滴答数。 当 FF_FS_REENTRANT == 0 时，此选项无效。

FF_SYNC_t

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（给定的参数无效，或者卷存在不一致的参数。）

文件访问类

f_open() – 打开或者创建一个文件

描述：
f_open函数的作用是打开一个文件并创建一个文件对象。它是文件后续读/写操作的标识符。函数成功后，文件对象有效。如果函数失败，则文件对象设置无效。

打开文件后应使用f_close函数关闭该文件的会话访问。如果对文件进行了任何更改，并且在断电、删除介质或重新挂载之前未关闭，则可以将文件折叠。

如果需要打开复制文件，请仔细阅读此处。然而，使用任何写模式标记的文件的重复打开总是被禁止的。

总是可用的。当FF_FS_READONLY == 1（文件权限为只读）时，模式标志只有FA_READ和FA_OPEN_EXISTING可用。

FRESULT f_open (
  FIL* fp,           /* [OUT] 指向空白文件对象结构的指针 */
  const TCHAR* path, /* [IN] 文件名 指向以空结束的字符串的指针，该字符串指定要打开或创建的文件名。*/
  BYTE mode          /* [IN] 模式标志，用于指定文件的访问类型和打开方法。 */
);

fr = f_open(&fil, "message.txt", FA_READ);
if (fr) return (int)fr;

Flags(参数mode)	meaning
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相同，只是读写指针设置在文件末尾。

f_open的返回码： 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_close() - 关闭一个打开的文件对象

描述：
f_close函数的作用是关闭一个打开的文件对象。如果文件已被更改，则该文件的缓存信息将被写回卷。函数成功后，文件对象不再有效，可以丢弃。

注意:如果文件对象处于只读模式，且没有启用FF_FS_LOCK，该文件对象也可以被丢弃，不需要执行此步骤。但是，为了将来的兼容性，不建议这样做。

FRESULT f_close (
  FIL* fp     /* [IN] 指向要关闭的打开文件对象结构的指针。 */
);
f_close(&fil);

f_close的返回码： FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_INVALID_OBJECT, FR_TIMEOUT

f_read() – 从文件中读数据

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

FRESULT f_read (
  FIL* fp,     /* [IN] Pointer to the open file object. */
  void* buff,  /* [OUT] 指向存储读取数据的缓冲区的指针。 */
  UINT btr,    /* [IN] 在UINT类型范围内要读取的字节数。如果需要快速读取文件，则应尽可能以大块进行读取。 */
 UINT* br     /* [OUT] 指向UINT变量的指针，该变量接收读取的字节数。不管函数的返回码是什么，这个值在函数调用之后总是有效的。如果返回值等于btr，函数返回码应该是FR_OK。 */
);
/* Example */ 
fr = f_read(&fsrc, buffer