STM32 高级说明 - FATFS 文件系统（下） - II.文件操作功能

2.1 f_open函数

• 函数功能：打开或者创建一个文件。
• 函数原型：FRESULT f_open (FIL* fp, const TCHAR* path, BYTE mode);
• 输入参数：*fp：指向一个空白文件对象的结构体指针；
  *path：文件名指针；
  mode：模式标志，共有以下几种模式：

模式	含义
FA_READ	指定对对象的读访问权限。可以从文件中读取数据。
FA_WRITE	指定对对象的写访问。数据可以写入文件。结合 FA _ READ 进行读写访问。
FA_OPEN_EXISTING	打开文件。如果文件不存在，函数将失败 (默认值)。
FA_OPEN_ALWAYS	如果文件存在，则打开该文件；如果没有，将创建一个新文件。
FA_CREATE_NEW	创建一个新文件。如果文件存在，函数将失败。
FA_CREATE_ALWAYS	创建一个新文件。如果该文件存在，它将被截断并覆盖。

  当 _ FS _ READONLY = = 1时（只读模式），模式标志 FA _ WRITE、 FA _ CREATE _ ALWAYS、 FA _ CREATE _ NEW 和 FA _ OPEN _ ALWAYS 不可用。

• 返回值：返回值是一个结构体，这里在每一个返回值后面给出了中文描述，仅供参考。

typedef enum {
	FR_OK = 0,				/* (0) 成功*/
	FR_DISK_ERR,			/* (1) 低级磁盘 I/O 层发生了一个硬错误 */
	FR_INT_ERR,				/* (2) 断言失败 */
	FR_NOT_READY,			/* (3) 物理驱动无法工作 */
	FR_NO_FILE,				/* (4) 无法找到文件 */
	FR_NO_PATH,				/* (5) 无法找到路径 */
	FR_INVALID_NAME,		/* (6) 路径名格式无效 */
	FR_DENIED,				/* (7) 由于禁止访问或目录已满而拒绝访问 */
	FR_EXIST,				/* (8) 由于禁止访问而拒绝访问 */
	FR_INVALID_OBJECT,		/* (9) 文件/目录对象无效 */
	FR_WRITE_PROTECTED,		/* (10) 物理驱动器受写保护 */
	FR_INVALID_DRIVE,		/* (11) 逻辑驱动器号无效 */
	FR_NOT_ENABLED,			/* (12) 卷没有工作区 */
	FR_NO_FILESYSTEM,		/* (13) 没有有效的FAT卷 */
	FR_MKFS_ABORTED,		/* (14) 由于任何参数错误，f _ mkfs ()中止 */
	FR_TIMEOUT,				/* (15) 无法获得在规定期限内访问卷的授权 */
	FR_LOCKED,				/* (16) 根据文件共享策略拒绝该操作 */
	FR_NOT_ENOUGH_CORE,		/* (17) 无法分配 LFN工作缓冲区 */
	FR_TOO_MANY_OPEN_FILES,	/* (18) 打开的文件数 > _ FS _ SHARE */
	FR_INVALID_PARAMETER	/* (19) 给定的参数无效 */
} FRESULT;

• 注意事项：在使用任何文件函数之前，必须使用 f _ mount 函数将工作区(文件系统对象)注册到逻辑驱动器（f_mount 函数后续会介绍）。除 f _ fdisk 函数之外的所有 API 函数都可以在此过程之后工作。打开的文件必须在断电、删除媒体或重新挂载之前关闭，否则文件可能会被折叠。若要关闭打开的文件，请使用 f _ close 函数。禁止复制打开任何写模式标志的文件。。

2.2 f_close函数

• 函数功能：关闭一个打开的文件。
• 函数原型：FRESULT f_close (FIL* fp);
• 输入参数：*fp：指向要关闭的打开文件对象结构的指针。
• 返回值：包含在FRESULT结构体，不再详细介绍。
• 注意事项：如果任何数据已经写入文件，文件的缓存信息将被写回卷。函数成功执行后，file 对象不再有效，可以将其丢弃。

2.3 f_read函数

• 函数功能：从一个文件中读取数据。
• 函数原型：FRESULT f_read (FIL* fp, void* buff, UINT btr, UINT* br);
• 输入参数：*fp：指向打开文件对象的指针；
  *buff：指向存储读取数据的数组指针；
  btr：在 UINT 类型范围内要读取的字节数；
  *br：指向 UINT 变量的指针，以返回读取的字节数。无论结果如何，该值在函数调用后始终有效；
• 返回值：包含在FRESULT结构体，不再详细介绍。
• 注意事项：文件对象的文件读/写指针提高了读取的字节数。函数完成后，应该检查 * br 以检测文件的结尾。如果 * br 小于 btr，则表示在读操作期间读/写指针到达文件末尾。

2.4 f_write函数

• 函数功能：往文件里写入数据。
• 函数原型：FRESULT f_write (FIL* fp, const void* buff, UINT btw, UINT* bw);
• 输入参数：*fp：指向打开文件对象的指针；
  *buff：指向要写入的数据的指针；
  btw：指定要在 UINT 类型范围内写入的字节数；
  *bw：指向 UINT 变量的指针，以返回写入的字节数；
• 返回值：包含在FRESULT结构体，不再详细介绍。
• 注意事项：函数完成后，应该检查 * bw 以检测磁盘是否已满。如果 * bw 小于 btw，则表示在写操作期间卷已满。该函数可以在卷满或接近满时执行。

  经测试发现，写完成后必须关闭文件才能保存写的数据，如果写完成后不关闭文件直接读取，新写入的内容不会被读取出来。

2.5 f_size获取文件大小

  f_size 函数获取文件的大小，返回文件的大小（以字节为单位）。它是作为宏实现的，只需要输入一个指向打开的文件对象结构的指针即可，使用比较简单，这里之所以单独介绍这个函数，是因为我们后续在使用SD卡读取文件时，很多时候需要先知道文件大小，然后开辟合适的空间来存储读取出来的文件内容。f_size函数的定义如下

#define f_size(fp) ((fp)->fsize)