FatFs文件系统常用函数

FatFs文件系统

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

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（限制最大打开数量），则也可以在不执行此过程的情况下丢弃该文件对象。但是，为了将来的兼容性，不建

议这样做。

使用条件：            

始终可用

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则表明文件读取到文件末尾

使用条件：            

始终可用

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 时可用。

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)

————————————————

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 时可用。

————————————————

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 时可用。

————————————————

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 而没有错误，则表示由于文件结束或流在数据传输期间繁忙，无法传输请求的数据大小。  

————————————————

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 时可用。

————————————————

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

FSIZE_t f_tell (

  FIL* fp   /* [IN] File object */

);

参数：

    @fp：文件指针

返回值：

    文件指针的位置，也就是光标的位置，距离文件开头的位置

描述：

    此函数为宏

    #define f_tell(fp) ((fp)->fptr)

使用条件：

    始终可用

————————————————

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

int f_eof (

  FIL* fp   /* [IN] File object */

);

参数：

    @fp：文件指针

返回值：

    如果读/写指针到达文件末尾，则 f_eof 函数返回非零值;否则返回零。

描述：

    此函数为宏

    #define f_eof(fp) ((int)((fp)->fptr == (fp)->fsize)) 

使用条件：

    始终可用

————————————————

12、 f_size获取文件的大小

FSIZE_t f_size (

  FIL* fp   /* [IN] File object */

);

参数：

    @fp：文件指针

返回值：

    以文件为字节返回文件的大小

描述：

    此函数为宏

    #define f_size(fp) ((fp)->obj.objsize)

使用条件：

    始终可用

————————————————

13、 f_error测试文件上的错误

int f_error (

 FIL* fp   /* [IN] File object */

);

参数：

   文件指针

返回值：

如果发生硬错误，则返回非零值;否则返回零。

描述：

   此函数为宏

   #define f_error(fp) ((fp)->err)

使用条件：

   始终可用    

————————————————