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:

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

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]typeflag：(-)左对齐，(0)填充0，默认右对齐空格填充width：1-99和'*'，如果宽度不够则会以空格或者0填充，默认设置0precision：指定字符串的小数位数或最大宽度，.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)
使用条件：始终可用