FatFS文件系统函数使用笔记

FatFS官方网站链接： FatFs - Generic FAT Filesystem Module

1，FatFs简介

概念：

        FatFs 是一个通用的文件系统(FAT/exFAT)模块，用于在小型嵌入式系统中实现FAT文件系统。 FatFs 组件的编写遵循ANSI C(C89)，完全分离于磁盘 I/O 层,因此不依赖于硬件平台。它可以嵌入到资源有限的微控制器中，如 8051, PIC, AVR, ARM, Z80, RX等等，不需要做任何修改。

特点：

（1）DOS/Windows兼容的FAT/exFAT文件系统
（2）平台独立性，容易使用
（3）程序代码量少，占用资源低

应用接口函数：

文件访问
    f_open - 打开/创建文件
    f_close - 关闭打开的文件
    f_read - 从文件中读取数据
    f_write - 将数据写入文件
    f_lseek - 移动读/写指针，扩展大小
    f_truncate - 截断文件大小
    f_sync - 刷新缓存数据
    f_forward - 将数据转发到流
    f_expand - 为文件分配一个连续的块
    f_gets - 读取字符串
    f_putc - 写一个字符
    f_puts - 写一个字符串
    f_printf - 写一个格式化的字符串
    f_tell - 获取当前读/写指针
    f_eof - 测试文件结尾
    f_size - 获取大小
    f_error - 测试错误
目录访问
    f_opendir - 打开一个目录
    f_closedir - 关闭一个打开的目录
    f_readdir - 读取目录项
    f_findfirst - 打开一个目录并读取匹配的第一个项目
    f_findnext - 读取下一个匹配的项目
文件和目录管理
    f_stat - 检查文件或子目录是否存在
    f_unlink - 删除文件或子目录
    f_rename - 重命名/移动文件或子目录
    f_chmod - 更改文件或子目录的属性
    f_utime - 更改文件或子目录的时间戳
    f_mkdir - 创建一个子目录
    f_chdir - 更改当前目录
    f_chdrive - 更改当前驱动器
    f_getcwd - 检索当前目录和驱动器
卷管理和系统配置
    f_mount - 注册/取消注册卷的工作区
    f_mkfs - 在逻辑驱动器上创建 FAT 卷
    f_fdisk - 在物理驱动器上创建分区
    f_getfree - 获取卷上的可用空间
    f_getlabel - 获取卷标
    f_setlabel - 设置卷标
    f_setcp - 设置活动代码页

2，应用接口函数详解

f_mount - 注册/取消注册卷的工作区：

        f_mount 功能为 FatFs 模块提供了工作区。

函数原型：

FRESULT f_mount (
   FATFS* fs, /* [IN] 文件系统对象 */
   const TCHAR* path, /* [IN] 逻辑驱动器号 */
   BYTE opt /* [IN] 初始化选项 */
);

FRESULT f_unmount (
   const TCHAR* path /* [IN] 逻辑驱动器号 */
);

参数：

        fs：指向要注册和清除的文件系统对象的指针。 空指针取消注册已注册的文件系统对象。     

        path：指向指定逻辑驱动器的以空字符结尾的字符串的指针。 没有驱动器号的字符串表示默认驱动器。

        opt：0：现在不挂载（要在第一次访问卷时挂载），1：强制挂载卷以检查它是否可以工作。

返回值：

        FR_OK (0)：函数成功。

        FR_INVALID_DRIVE：驱动器号无效

描述：

        f_mount函数在FatFs模块上注册/注销一个工作区。在使用任何其他文件函数之前，必须使用该函数为每个卷注册一个工作区。要注销一个工作区，只要指定FileSystemObject为NULL即可，然后该工作区可以被丢弃。该函数只初始化给定的工作区，以及将该工作区的地址注册到内部表中，不访问磁盘I/O层。卷装入过程是在f_mount函数后或存储介质改变后的第一次文件访问时完成的。

要取消注册工作区， fs 指定 NULL，然后可以丢弃工作区。 f_unmount 函数是作为宏实现的。

#define f_unmount(path) f_mount(0, path, 0)

f_open - 打开/创建文件：

        f_open 函数打开一个文件。

函数原型：

FRESULT f_open (
   FIL* fp, /* [OUT] 指向文件对象结构的指针 */
   const TCHAR* Path，/* [IN] 文件名 */
   BYTE mode /* [IN] 模式标志 */
);

参数：

        fs：指向空白文件对象结构的指针。     

        path：指向指定要打开或创建的文件名的空终止字符串的指针。

        mode：指定文件的访问类型和打开方法的模式标志。 它由以下标志的组合指定。

Flags	Meaning
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

返回值：

        FR_OK (0)：函数成功，该文件对象有效。

        FR_NO_FILE：找不到该文件。

        FR_NO_PATH：找不到该路径。

        FR_INVALID_NAME：文件名无效。

        FR_INVALID_DRIVE：驱动器号无效。

        FR_EXIST：该文件已存在。

        FR_DENIED：由于下列原因，所需的访问被拒绝：

                （1）以写模式打开一个只读文件。

                （2）由于存在一个同名的只读文件或目录，而导致文件无法被创建。

                （3）由于目录表或磁盘已满，而导致文件无法被创建。

        FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

        FR_WRITE_PROTECTED：在存储介质被写保护的情况下，以写模式打开或创建文件对象。

        FR_DISK_ERR：由于底层磁盘I/O接口函数中的一个错误，而导致该函数失败。

        FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

        FR_NOT_ENABLED：逻辑驱动器没有工作区。

        FR_NO_FILESYSTEM：磁盘上没有有效地FAT卷。

描述：

        如果函数成功，则创建一个文件对象。该文件对象被后续的读/写函数用来访问文件。如果想要关闭一个打开的文件对象，则使用f_close函数。如果不关闭修改后的文件，那么文件可能会崩溃。在使用任何文件函数之前，必须使用f_mount函数为驱动器注册一个工作区。只有这样，其他文件函数才能正常工作。

f_close- 关闭一个打开的文件

原型：

        FRESULT f_close ( FIL* FileObject );

参数：

        FileObject：指向将被关闭的已打开的文件对象结构的指针。

返回值：

        FR_OK (0) 文件对象已被成功关闭。

        FR_DISK_ERR 由于底层磁盘I/O函数中的错误，而导致该函数失败。

        FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

        FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

        FR_INVALID_OBJECT：文件对象无效。

描述：

        f_close函数关闭一个打开的文件对象。无论向文件写入任何数据，文件的缓存信息都将被写回到磁盘。该函数成功后，文件对象不再有效，并且可以被丢弃。如果文件对象是在只读模式下打开的，不需要使用该函数，也能被丢弃。

f_read- 从一个文件读取数据

原型：

FRESULT f_read ( FIL* FileObject, void* Buffer, 首先要定义一个至少512的内存 UINT ByteToRead, UINT* ByteRead );

参数：

FileObject:指向将被读取的已打开的文件对象结构的指针。

Buffer:指向存储读取数据的缓冲区的指针。

ByteToRead:要读取的字节数，UINT范围内。

ByteRead:指向返回已读取字节数的UINT变量的指针。在调用该函数后，无论结果如何，数值都是有效的。

返回值:

FR_OK (0):函数成功。

FR_DENIED:由于文件是以非读模式打开的，而导致该函数被拒绝。

FR_DISK_ERR:由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR:由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_READY:由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_INVALID_OBJECT: 文件对象无效。

描述:

文件对象中的读/写指针以已读取字节数增加。该函数成功后，应该检查 *ByteRead 来检测文件是否结束。在读操作过程中，一旦 *ByteRead < ByteToRead ，则读/写指针到达了文件结束位置。

f_write- 写入数据到一个文件FRESULT

原型：

f_write ( FIL* FileObject, const void* Buffer, UINT ByteToWrite,UINT* ByteWritten );

参数：

FileObject：指向将被写入的已打开的文件对象结构的指针。

Buffer：指向存储写入数据的缓冲区的指针。

ByteToRead：要写入的字节数，UINT范围内。

ByteRead：指向返回已写入字节数的UINT变量的指针。在调用该函数后，无论结果如何，数值都是有效的。

返回值：

FR_OK (0)：函数成功。

FR_DENIED：由于文件是以非写模式打开的，而导致该函数被拒绝。

FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_INVALID_OBJECT 文件对象无效。

描述：

文件对象中的读/写指针以已写入字节数增加。该函数成功后，应该检查 *ByteWritten 来检测磁盘是否已满。在写操作过程中，一旦 *ByteWritten < *ByteToWritten ，则意味着该卷已满。

f_lseek- 移动一个打开的文件对象的文件读/写指针。也可以被用来扩展文件大小(簇预分配)。

原型：

FRESULT f_lseek ( FIL* FileObject, DWORD Offset );

参数：

FileObject：打开的文件对象的指针

Offset：相对于文件起始处的字节数

返回值：

FR_OK (0)：函数成功。

FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_INVALID_OBJECT：文件对象无效。

描述：

f_lseek函数当FS_MINIMIZE <= 2时可用。offset只能被指定为相对于文件起始处的字节数。当在写模式下指定了一个超过文件大小的offset时，文件的大小将被扩展，并且该扩展的区域中的数据是未定义的。这适用于为快速写操作迅速地创建一个大的文件。f_lseek函数成功后，为了确保读/写指针已被正确地移动，必须检查文件对象中的成员fptr。如果fptr不是所期望的值，则发生了下列情况之一。

（1）文件结束。指定的offset被钳在文件大小，因为文件已被以只读模式打开。

（2）磁盘满。卷上没有足够的空闲空间去扩展文件大小。

用法：其实这个函数可以解决文件从头开始读的问题，如果你想打开一个文件，读取里面的内容，但又不想从头开始读，那么你可以使用这个函数来解决

f_truncate- 截断文件大小

原型：

FRESULT f_truncate ( FIL* FileObject );

参数：

FileObject：待截断的打开的文件对象的指针。

返回值：

FR_OK (0：函数成功。

FR_DENIED：由于文件是以非写模式打开的，而导致该函数被拒绝。

FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_INVALID_OBJECT 文件对象无效。

描述：

f_truncate函数当_FS_READONLY == 0 并且 _FS_MINIMIZE == 0时可用。f_truncate函数截断文件到当前的文件读/写指针。当文件读/写指针已经指向文件结束时，该函数不起作用。

f_sync- 冲洗一个写文件的缓存信息

原型：

FRESULT f_sync ( FIL* FileObject );

参数：

FileObject：待冲洗的打开的文件对象的指针。

返回值：

FR_OK (0)：函数成功。

FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_INVALID_OBJECT 文件对象无效。

描述：

f_sync函数当_FS_READONLY == 0时可用。f_sync函数和f_close函数执行同样的过程，但是文件仍处于打开状态，并且可以继续对文件执行读/写/移动指针操作。这适用于以写模式长时间打开文件，比如数据记录器。定期的或f_write后立即执行f_sync可以将由于突然断电或移去磁盘而导致数据丢失的风险最小化。在f_close前立即执行f_sync没有作用，因为在f_close中执行了f_sync。换句话说，这两个函数的差异就是文件对象是不是无效的。

f_opendir- 打开一个目录

原型：

FRESULT f_opendir ( DIR* DirObject, const XCHAR* DirName );

参数：

DirObject：待创建的空白目录对象的指针。

DirName：'\0'结尾的字符串指针，该字符串指定了将被打开的目录名。

返回值：

FR_OK (0)：函数成功，目录对象被创建。该目录对象被后续调用，用来读取目录项。

FR_NO_PATH：找不到路径。

FR_INVALID_NAME：路径名无效。

FR_INVALID_DRIVE：驱动器号无效。

FR_NOT_READY：由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。

FR_DISK_ERR：由于底层磁盘I/O函数中的错误，而导致该函数失败。

FR_INT_ERR：由于一个错误的FAT结构或一个内部错误，而导致该函数失败。

FR_NOT_ENABLED：逻辑驱动器没有工作区。

FR_NO_FILESYSTEM：磁盘上没有有效的FAT卷。

描述：

f_opendir函数当_FS_MINIMIZE <= 1时可用。f_opendir函数打开一个已存在的目录，并为后续的调用创建一个目录对象。该目录对象结构可以在任何时候不经任何步骤而被丢弃。