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'。
	

image-20230321154750651

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)
使用条件:
   始终可用     
物联沃分享整理
物联沃-IOTWORD物联网 » FatFS的文件操作

发表评论