FatFS的文件操作

1、文件操作

1.1、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：文件路径(文件名)
	@mode：打开方式
返回值：
	成功返回FR_OK（0），文件对象有效
	失败则文件对象无效（NULL）
	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关闭文件
	如果对文件进行了更改，并且在断电、删除介质或从新挂载前未关闭，则文件可能会崩溃
	只能以读的方式重复打开一个文件，不能以任何具有写模式的方式重复打开一个文件(第二次打开不成功 FR_LOCKED, 哪怕第二次是只读、只打开)
	当把FATFS配置为只读模式（FF_FS_READONLY == 1）的时候，mode只能FA_READ和FA_OPEN_EXISTING
使用条件：     
	始终可用

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相同，只是读/写指针设置在文件的末尾。

POSIX fopen（） 函数中的模式标志对应于 FatFs 模式标志，如下所示：

POSIX	FatFs
“r”	FA_READ
“r+”	FA_READ | FA_WRITE
“w”	FA_CREATE_ALWAYS | FA_WRITE
“w+”	FA_CREATE_ALWAYS | FA_WRITE | FA_READ
“a”	FA_OPEN_APPEND | FA_WRITE
“a+”	FA_OPEN_APPEND | FA_WRITE | FA_READ
“wx”	FA_CREATE_NEW | FA_WRITE
“w+x”	FA_CREATE_NEW | FA_WRITE | FA_READ

1.2、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（double free）、FR_TIMEOUT
描述：
 f_close函数关闭打开的文件对象。如果文件已更改，则文件的缓存信息将写回卷。函数成功后，文件对象不再有效（在函数中将文件指针置为0），可以丢弃。请注意，如果文件对象处于只读模式且未启用FF_FS_LOCK（限制最大打开数量），则也可以在不执行此过程的情况下丢弃该文件对象。但是，为了将来的兼容性，不建议这样做。

使用条件：    	
	始终可用

1.3、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：想要读取的数据
 @br：实际读取的数据。无论函数返回代码如何，此值在函数调用后始终有效。如果返回值等于 btr，则函数返回代码应FR_OK。
返回值：
 FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_DENIED、FR_INVALID_OBJECT FR_TIMEOUT
描述：
 读取文件后，文件的读写指针（可以理解为光标）将会向后偏移
 函数执行成功后，*br < btr则表明文件读取到文件末尾

使用条件：    	
	始终可用

1.4、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：要写入数据的存放地址，如果需要快速写入数据则空间应该因尽量的大
 @btr：想要读取的数据
 @br：实际读取的数据针。无论函数返回代码如何，此值在函数调用后始终有效。如果返回值等于 btw，则函数返回代码应FR_OK。
描述：
 函数成功后，应检查*bw以检测磁盘已满。如果是 *bw < btw，则表示卷在写入操作期间已满。当卷已满或接近满时（写满后进入我写的delay,没看出现象），该函数可能需要一段时间。

使用条件：    	
	当FF_FS_READONLY == 0 时可用。

1.5、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 位）（exFAT）的别名，具体取决于FF_FS_EXFAT配置选项。
返回值：
 FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_INVALID_OBJECT、FR_TIMEOUT

描述：
 如果在写入模式下指定了超出文件大小的偏移量，则文件大小将扩展到指定的偏移量。留下的空间，但是在此过程中并没有写入数据。若是函数执行成功但是指针却没有偏移，则可能是：
 	文件结束。指定的 ofs 以只读模式在文件末尾剪裁。
	磁盘已满。卷上没有可用空间来扩展文件。

使用条件：
 当FF_FS_MINIMIZE <= 2 时可用。要使用快速查找功能，需要将FF_USE_FASTSEEK设置为 1 以启用此功能（当FF_FS_MINIMIZE = 3时删除了f_lseek）

f_rewind（光标移动到文件开头）函数作为宏：
	#define f_rewind(fp) f_lseek((fp), 0)

1.6、f_truncate截断文件

FRESULT f_truncate (
FIL* fp     /* [IN] File object */
);
参数：
 文件指针
返回值：
 FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_DENIED（操作只读函数）、FR_INVALID_OBJECT、FR_TIMEOUT
描述：
 将文件截断为当前文件文件指针所在的大小，如果文件指针指向末尾则不起作用。

使用条件：
 当FF_FS_READONLY == 0 和 FF_FS_MINIMIZE == 0 时可用。

1.7、f_sync冲刷数据缓冲区

FRESULT f_sync (
FIL* fp     /* [IN] File object */
);
参数：
 @fp：文件指针
返回值：
 FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_INVALID_OBJECT、FR_TIMEOUT
描述：
 文件在写入的时候会暂存在文件缓冲区，只有遇到刷新条件的时候才会将写缓冲区的数据写入到文件中，但是在未将缓冲区的数据冲刷到缓冲区之前突然发生错误，那么写入的信息就丢失了。

使用条件：
 当FF_FS_READONLY == 0 时可用。

1.8、f_forward读取文件数据并将其转发到数据流设备

FRESULT f_forward (
FIL* fp,                        /* [IN] File object */
UINT (*func)(const BYTE*,UINT), /* [IN] Data streaming function */
UINT btf,                       /* [IN] Number of bytes to forward */
UINT* bf                        /* [OUT] Number of bytes forwarded */
);
参数：
   @fp：文件指针
   @func：数据处理函数
   @btf：传输的数据大小
   @bf：实际传输的数据
参数：
	FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_INVALID_OBJECT、FR_DENIED、FR_TIMEOUT
描述：
   如果 *bf 小于 btf 而没有错误，则表示由于文件结束或流在数据传输期间繁忙，无法传输请求的数据大小。    

1.9、 f_expand 为文件准备或分配一个连续的区域

FRESULT f_expand (
  FIL*    fp,  /* [IN] File object */
  FSIZE_t fsz, /* [IN] File size expanded to */
  BYTE    opt  /* [IN] Allocation mode */
);
参数：
    @fp：文件指针
    @fsz：分配空间的大小
    @opt：分配模式（0）准备分配、（1）立即分配
返回值：
    FR_OK、FR_DISK_ERR、FR_INT_ERR、FR_INVALID_OBJECT、FR_DENIED、FR_TIMEOUT
描述：
    为一个空文件分配连续的空间，必须是空文件，函数执行完之后读写指针（光标）在文件开头，在分配空间的时候不会像文件写入数据，由于以下一些原因，该函数可能会因FR_DENIED而失败。
    未找到可用的连续空间。
    文件大小不为零。
    该文件已以只读模式打开。
    不允许的文件大小。（>= 4 GB 的 FAT 卷）
使用条件：
    当FF_USE_EXPAND == 1 和 FF_FS_READONLY == 0 时可用。

1.10、f_gets 从文件中读取字符串

TCHAR* f_gets (
  TCHAR* buff, /* [OUT] Read buffer */
  int len,     /* [IN] Size of the read buffer */
  FIL* fp      /* [IN] File object */
);
参数：
    @buff：读到数据存放的空间
    @len：想要读多长
    @fp：文件指针
返回值：
    成功返回buff，读到文件末尾或者失败返回NULL,可以通过f_eof和f_error判断
描述：
    读到'\n'、文件末尾、缓冲区(len - 1)（-1是因为有'\0'）结束。
    文件的编码格式和FATFS配置的编码格式不同时，此函数将会转换该文件，在种情况下，错误的编码将会丢失。

使用条件：
    这是f_read函数的包装函数。当FF_USE_STRFUNC >= 1 时可用。当它设置为 2 时，文件中包含的 '\r 将被去除。

1.11、f_putc将字符放入文件中

int f_putc (
  TCHAR chr,  /* [IN] A character to write */
  FIL* fp     /* [IN] File object */
);
参数：
    @chr：要写的字符
    @fp：文件结构体指针
返回值：
    成功返回返回写入字符的个数，失败返回负值
描述：
    当FATFS配置为Unicode API （FF_LFN_UNICODE >= 1）时，f_putc、f_puts、f_printf和f_gets函数上的字符编码也会切换到 Unicode。通过这些功能读取/写入的文件上的字符编码由FF_STRF_ENCODE选择。多个编码单元中的 Unicode 字符（如代理项对和多字节序列）不能使用此函数写入。 
    
使用条件：
    这是f_write函数的包装函数。当FF_FS_READONLY == 0 且FF_USE_STRFUNC >= 1 时可用。当 FF_USE_STRFUNC == 2 时，输出 '\n' 为 '\r'+'\n'。

1.12、f_puts将字符串写入文件中

int f_puts (
  const TCHAR* str, /* [IN] String */
  FIL* fp           /* [IN] File object */
);
参数：
    @str：要写入的字符串
    @fp：文件指针
返回值：
    成功返回写入的长度，失败返回负值
描述：
    和f_putc一样有编码问题
使用条件：
    这是f_write函数的包装函数。当FF_FS_READONLY == 0 且FF_USE_STRFUNC >= 1 时可用。当 FF_USE_STRFUNC == 2 时，输入字符串中包含的 '\n 将分别输出为 '\r'+'\n'。

1.13、f_printf 将格式化字符串写入文件

int f_printf (
  FIL* fp,          /* [IN] File object */
  const TCHAR* fmt, /* [IN] Format stirng */
  ...
);
参数：
    @fp：文件指针
    @fmt：格式化字符串
    @...：可选参数，fmt和...和printf的参数一致
返回值：
    写入成功返回写入的字符串，失败返回负值
描述：
    %[flag][width][precision][size]type
    flag：(-)左对齐，(0)填充0，默认右对齐空格填充
    width：1-99和'*'，如果宽度不够则会以空格或者0填充，默认设置0
    precision：指定字符串的小数位数或最大宽度，.0-.99 或 .*。如果省略该数字，则与 .0 相同。数字的默认设置为 6，字符串没有限制。
     size：指定整数参数 l（long） 和 ll（long long） 的大小。如果 sizeof （long） == sizeof （int） 为真（这是 32 位系统的典型特征），则可以省略长整数参数的前缀 l。整数参数的默认大小为 int，浮点参数始终假定为双精度。
	如果编码不需要转换的话，使用sprintf+f_write是相同的效果
    
使用条件：
    这是f_write函数的包装函数。当FF_FS_READONLY == 0 且FF_USE_STRFUNC >= 1 时可用。当FF_USE_STRFUNC == 2 时，生成的字符串中的 '\n 分别写为 '\r'+'\n'。
	

1.14、 f_tell获取当前文件指针的位置

FSIZE_t f_tell (
  FIL* fp   /* [IN] File object */
);
参数：
    @fp：文件指针
返回值：
    文件指针的位置，也就是光标的位置，距离文件开头的位置
描述：
    此函数为宏
    #define f_tell(fp) ((fp)->fptr)
使用条件：
    始终可用

1.15、f_eof判断文件指针是否在文件尾

int f_eof (
  FIL* fp   /* [IN] File object */
);
参数：
    @fp：文件指针
返回值：
    如果读/写指针到达文件末尾，则 f_eof 函数返回非零值;否则返回零。
描述：
    此函数为宏
    #define f_eof(fp) ((int)((fp)->fptr == (fp)->fsize))  
使用条件：
    始终可用

1.16、 f_size获取文件的大小

FSIZE_t f_size (
  FIL* fp   /* [IN] File object */
);
参数：
    @fp：文件指针
返回值：
    以文件为字节返回文件的大小
描述：
    此函数为宏
    #define f_size(fp) ((fp)->obj.objsize)
使用条件：
    始终可用

1.17、 f_error测试文件上的错误

int f_error (
 FIL* fp   /* [IN] File object */
);
参数：
   文件指针
返回值：
	如果发生硬错误，则返回非零值;否则返回零。
描述：
   此函数为宏
   #define f_error(fp) ((fp)->err)
使用条件：
   始终可用