FATFS文件系统常用函数记录

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：要写入数据的存放地址，如果需要快速写入数据则空间应该尽量大
• @btw：想要写入的数据字节数
• @bw：实际写入的数据字节数。无论函数返回代码如何，此值在函数调用后始终有效。如果返回值等于 btw，则函数返回代码应为 FR_OK

返回值：

• FR_OK
• FR_DISK_ERR
• FR_INT_ERR
• FR_DENIED
• FR_INVALID_OBJECT
• FR_TIMEOUT

描述：

• 函数成功后，应检查 *bw 以检测磁盘是否已满。如果 *bw < btw，则表示卷在写入操作期间已满。当卷已满或接近满时，该函数可能需要一段时间。

使用条件：

• 当 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 */
);

参数：

• @fp：文件指针

返回值：

• 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 */
);

参数：

• @fp：文件指针

返回值：

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

描述：

• 此函数为宏：

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

使用条件：

• 始终可用

博客

欢迎访问我的博客