FatFs 通用 FAT 文件系统模块
中文手册
版本:R0.009a
FatFs通用 FAT 文件系统模块
目录
1、特点 ....................................................................................................................................................................... 1
2、应用程序接口 ....................................................................................................................................................... 2
2.1 f_mount ......................................................................................................................................................... 3
2.2 f_open ............................................................................................................................................................ 4
2.3 f_close ............................................................................................................................................................ 6
2.4 f_read ............................................................................................................................................................. 7
2.5 f_write ............................................................................................................................................................ 8
2.6 f_lseek ............................................................................................................................................................ 9
2.7 f_truncate .................................................................................................................................................... 10
2.8 f_sync ........................................................................................................................................................... 11
2.9 f_opendir ..................................................................................................................................................... 12
2.10 f_readdir .................................................................................................................................................... 13
2.11 f_getfree .................................................................................................................................................... 15
2.12 f_stat .......................................................................................................................................................... 16
2.13 f_mkdir ....................................................................................................................................................... 17
2.14 f_unlink ...................................................................................................................................................... 18
2.15 f_chmod ..................................................................................................................................................... 19
2.16 f_utime ...................................................................................................................................................... 20
2.17 f_rename ................................................................................................................................................... 21
2.18 f_chdir ........................................................................................................................................................ 22
2.19 f_chdrive .................................................................................................................................................... 23
2.20 f_getcwd .................................................................................................................................................... 24
2.21 f_forward ................................................................................................................................................... 25
2.22 f_mkfs ........................................................................................................................................................ 27
2.23 f_fdisk ........................................................................................................................................................ 28
2.24 f_gets ......................................................................................................................................................... 29
2.25 f_putc ......................................................................................................................................................... 30
2.26 f_puts ......................................................................................................................................................... 31
2.27 f_printf ....................................................................................................................................................... 32
2.28 f_tell ........................................................................................................................................................... 33
2.29 f_eof ........................................................................................................................................................... 34
2.30 f_size .......................................................................................................................................................... 35
2.31 f_error ........................................................................................................................................................ 36
3、磁盘 I/O接口 ...................................................................................................................................................... 37
3.1 disk_initialize ............................................................................................................................................... 37
3.2 disk_status ................................................................................................................................................... 37
3.3disk_read ...................................................................................................................................................... 38
3.4 disk_write .................................................................................................................................................... 38
3.5 disk_ioctl ...................................................................................................................................................... 39
3.6 get_fattime .................................................................................................................................................. 40
4、FatFs模块应用 .................................................................................................................................................... 41
4.1 如何移植 .................................................................................................................................................... 41
FatFs通用 FAT 文件系统模块
4.1.1 基本概念 ......................................................................................................................................... 41
4.1.2 系统组织 ......................................................................................................................................... 41
4.1.3 需要哪些函数? ............................................................................................................................. 41
4.2 限制 ............................................................................................................................................................ 42
4.3 内存使用(R0.09a) ........................................................................................................................................ 42
4.4 模块大小裁减 ............................................................................................................................................. 42
4.5 长文件名 .................................................................................................................................................... 43
4.6 Unicode API .................................................................................................................................................. 43
4.7 重入 ............................................................................................................................................................ 44
4.8 重复的文件访问 ........................................................................................................................................ 44
4.9 执行有效的文件访问 ................................................................................................................................ 44
4.10 关于闪存媒体的考虑 .............................................................................................................................. 45
4.10.1 使用多扇区写 ............................................................................................................................... 45
4.10.2 强制内存擦除 ............................................................................................................................... 45
4.11 临界区(Critical Section) ...................................................................................................................... 46
FatFs通用 FAT 文件系统模块
1
FatFs 是一个为小型嵌入式系统设计的通用 FAT(File Allocation Table)文件系统模块。FatFs 的编写遵循
ANSI C,并且完全与磁盘 I/O 层分开。因此,它独立(不依赖)于硬件架构。它可以被嵌入到低成本的微控制
器中,如 AVR、8051、PIC、ARM、Z80、68K 等等,而不需要做任何修改。
1、特点
Windows 兼容的 FAT 文件系统
不依赖于平台,易于移植
代码和工作区占用空间非常小
多种配置选项:
z 多卷(物理驱动器和分区)
z 多 ANSI/OEM 代码页,包括 DBCS
z 在 ANSI/OEM 或 Unicode 中长文件名的支持
z RTOS 的支持
z 多扇区大小的支持
z 只读,最少 API,I/O 缓冲区等等
FatFs通用 FAT 文件系统模块
2
2、应用程序接口
FatFs 模块为应用程序提供了下列函数,这些函数描述了 FatFs 能对 FAT 卷执行哪些操作。
函数名 描述
f_mount 注册/注销一个工作区
f_open 打开/创建一个文件
f_close 关闭一个文件
f_read 读取文件
f_write 写文件
f_lseek 移动读/写指针,扩展文件大小
f_truncate 截断文件大小
f_sync 清空缓冲数据
f_opendir 打开一个目录
f_readdir 读取一个目录项
f_getfree 获取空闲簇
f_stat 获取文件状态
f_mkdir 创建一个目录
f_unlink 删除一个文件或目录
f_chmod 修改属性
f_utime 修改日间戳
f_rename 删除/移动一个文件或目录
f_chdir 修改当前目录
f_chdrive 修改当前驱动器
f_getcwd 恢复当前目录
f_forward 直接输出文件数据流
f_mkfs 在驱动器上创建一个文件系统
f_fdisk 划分一个物理驱动器
f_gets 读取一个字符串
f_putc 写一个字符
f_puts 写一个字符串
f_printf 写一个格式化的字符串
f_tell 获取当前读/写指针
f_eof 测试一个文件是否到达文件末尾
f_size 获取一个文件的大小
f_error 测试一个文件是否出错
FatFs通用 FAT 文件系统模块
3
2.1 f_mount
在 FatFs 模块上注册/注销一个工作区(文件系统对象)。
FRESULT f_mount (
BYTE Drive, /* 逻辑驱动器号 */
FATFS* FileSystemObject /* 工作区指针 */
);
参数
Drive 注册/注销工作区的逻辑驱动器号(0-9)。
FileSystemObject 工作区(文件系统对象)指针。
返回值
FR_OK (0)函数成功。
FR_INVALID_DRIVE 驱动器号无效
描述
f_mount 函数在 FatFs 模块上注册/注销一个工作区。在使用任何其他文件函数之前,必须使用该函数为
每个卷注册一个工作区。要注销一个工作区,只要指定 FileSystemObject 为 NULL 即可,然后该工作区可以
被丢弃。
该函数只初始化给定的工作区,以及将该工作区的地址注册到内部表中,不访问磁盘 I/O 层。卷装入过
程是在 f_mount 函数后或存储介质改变后的第一次文件访问时完成的。
FatFs通用 FAT 文件系统模块
4
2.2 f_open
创建/打开一个用于访问文件的文件对象
FRESULT f_open (
FIL* FileObject, /* 空白文件对象结构指针 */
const XCHAR* FileName, /* 文件名指针 */
BYTE ModeFlags /* 模式标志 */
);
参数
FileObject 将被创建的文件对象结构的指针。
FileName
NULL 结尾的字符串指针,该字符串指定了将被创建或打开的文件名。
ModeFlags 指定文件的访问类型和打开方法。它是由下列标志的一个组合指定的。
模式 描述
FA_READ
指定读访问对象。可以从文件中读取数据。
与 FA_WRITE 结合可以进行读写访问。
FA_WRITE
指定写访问对象。可以向文件中写入数据。
与 FA_READ 结合可以进行读写访问。
FA_OPEN_EXISTING 打开文件。如果文件不存在,则打开失败。(默认)
FA_OPEN_ALWAYS 如果文件存在,则打开;否则,创建一个新文件。
FA_CREATE_NEW 创建一个新文件。如果文件已存在,则创建失败。
FA_CREATE_ALWAYS 创建一个新文件。如果文件已存在,则它将被截断并覆盖。
注意:当 _FS_READONLY == 1 时,模式标志 FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW,
FA_OPEN_ALWAYS 是无效的。
返回值
FR_OK (0)函数成功,该文件对象有效。
FR_NO_FILE 找不到该文件。
FR_NO_PATH 找不到该路径。
FR_INVALID_NAME 文件名无效。
FR_INVALID_DRIVE 驱动器号无效。
FR_EXIST 该文件已存在。
FR_DENIED 由于下列原因,所需的访问被拒绝:
• 以写模式打开一个只读文件。
• 由于存在一个同名的只读文件或目录,而导致文件无法被创建。
• 由于目录表或磁盘已满,而导致文件无法被创建。
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 函数为驱动器注册一个工作区。只有这样,其他文件函数
FatFs通用 FAT 文件系统模块
5
才能正常工作。
示例(文件拷贝)
void main (void)
{
FATFS fs[2]; /* 逻辑驱动器的工作区(文件系统对象) */
FIL fsrc, fdst; /* 文件对象 */
BYTE buffer[4096]; /* 文件拷贝缓冲区 */
FRESULT res; /* FatFs 函数公共结果代码 */
UINT br, bw; /* 文件读/写字节计数 */
/* 为逻辑驱动器注册工作区 */
f_mount(0, &fs[0]);
f_mount(1, &fs[1]);
/* 打开驱动器 1 上的源文件 */
res = f_open(&fsrc, "1:srcfile.dat", FA_OPEN_EXISTING | FA_READ);
if (res) die(res);
/* 在驱动器 0 上创建目标文件 */
res = f_open(&fdst, "0:dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
if (res) die(res);
/* 拷贝源文件到目标文件 */
for (;;) {
res = f_read(&fsrc, buffer, sizeof(buffer), &br);
if (res || br == 0) break; /* 文件结束错误 */
res = f_write(&fdst, buffer, br, &bw);
if (res || bw < br) break; /* 磁盘满错误 */
}
/* 关闭打开的文件 */
f_close(&fsrc);
f_close(&fdst);
/* 注销工作区(在废弃前) */
f_mount(0, NULL);
f_mount(1, NULL);
}
FatFs通用 FAT 文件系统模块
6
2.3 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 函数关闭一个打开的文件对象。无论向文件写入任何数据,文件的缓存信息都将被写回到磁盘。
该函数成功后,文件对象不再有效,并且可以被丢弃。如果文件对象是在只读模式下打开的,不需要使用
该函数,也能被丢弃。
FatFs通用 FAT 文件系统模块
7
2.4 f_read
从一个文件读取数据
FRESULT f_read (
FIL* FileObject, /* 文件对象结构的指针 */
void* Buffer, /* 存储读取数据的缓冲区的指针 */
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 ,则读/写指针到达了文件结束位置。
FatFs通用 FAT 文件系统模块
8
2.5 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 ,则意味着该卷已满。
FatFs通用 FAT 文件系统模块
9
2.6 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 不是所期望的值,则发生了下列情况之一。
z 文件结束。指定的 offset 被钳在文件大小,因为文件已被以只读模式打开。
z 磁盘满。卷上没有足够的空闲空间去扩展文件大小。
示例
/* 移动文件读/写指针到相对于文件起始处偏移为 5000 字节处 */
res = f_lseek(file, 5000);
/* 移动文件读/写指针到文件结束处,以便添加数据 */
res = f_lseek(file, file->fsize);
/* 向前 3000 字节 */
res = f_lseek(file, file->fptr + 3000);
/* 向后(倒带)2000 字节(注意溢出) */
res = f_lseek(file, file->fptr - 2000);
/* 簇预分配(为了防止在流写时缓冲区上溢 */
res = f_open(file, recfile, FA_CREATE_NEW | FA_WRITE); /* 创建一个文件 */
res = f_lseek(file, PRE_SIZE); /* 预分配簇 */
if (res || file->fptr != PRE_SIZE) ... /* 检查文件大小是否已被正确扩展 */
res = f_lseek(file, DATA_START); /* 没有簇分配延迟地记录数据流 */
...
res = f_truncate(file); /* 截断未使用的区域 */
res = f_lseek(file, 0); /* 移动到文件起始处 */
...
res = f_close(file);
FatFs通用 FAT 文件系统模块
10
2.7 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 函数截断文件到当前的文件读/写指针。当文件读/写指针已经指向文件结束时,该函数不起作
用。
FatFs通用 FAT 文件系统模块
11
2.8 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。换句话说,这两个函数的差异就是文件对象是不是无效的。
FatFs通用 FAT 文件系统模块
12
2.9 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 函数打开一个已存在的目录,并为后续的调用创建一个目录对象。该目录对象结构可以在任
何时候不经任何步骤而被丢弃。
FatFs通用 FAT 文件系统模块
13
2.10 f_readdir
读取目录项
FRESULT f_readdir (
DIR* DirObject, /* 指向打开的目录对象结构的指针 */
FILINFO* FileInfo /* 指向文件信息结构的指针 */
);
参数
DirObject 打开的目录对象的指针。
FileInfo 存储已读取项的文件信息结构指针。
返回值
FR_OK (0)函数成功。
FR_DISK_ERR 由于底层磁盘 I/O 函数中的错误,而导致该函数失败。
FR_INT_ERR 由于一个错误的 FAT 结构或一个内部错误,而导致该函数失败。
FR_NOT_READY 由于驱动器中没有存储介质或任何其他原因,而导致磁盘驱动器无法工作。
FR_INVALID_OBJECT 文件对象无效。
描述
f_readdir 函数当_FS_MINIMIZE <= 1 时可用。
f_readdir 函数顺序读取目录项。目录中的所有项可以通过重复调用 f_readdir 函数被读取。当所有目录
项已被读取并且没有项要读取时,该函数没有任何错误地返回一个空字符串到 f_name[]成员中。当 FileInfo
给定一个空指针时,目录对象的读索引将被回绕。
当 LFN 功能被使能时,在使用 f_readdir 函数之前,文件信息结构中的 lfname 和 lfsize 必须被初始化为
有效数值。lfname 是一个返回长文件名的字符串缓冲区指针。lfsize 是以字符为单位的字符串缓冲区的大小。
如果读缓冲区或 LFN 工作缓冲区的大小(对于 LFN)不足,或者对象没有 LFN,则一个空字符串将被返回到
LFN 读缓冲区。如果 LFN 包含任何不能被转换为 OEM 代码的字符,则一个空字符串将被返回,但是这不
是 Unicode API 配置的情况。当 lfname 是一个空字符串时,没有 LFN 的任何数据被返回。当对象没有 LFN
时,任何小型大写字母可以被包含在 SFN 中。
当相对路径功能被使能(_FS_RPATH == 1)时,"."和".."目录项不会被过滤掉,并且它将出现在读目录项
中。
示例
FRESULT scan_files (
char* path /* Start node to be scanned (also used as work area) */
)
{
FRESULT res;
FILINFO fno;
DIR dir;
int i;
char *fn; /* This function is assuming non-Unicode cfg. */
#if _USE_LFN
static char lfn[_MAX_LFN + 1];
fno.lfname = lfn;
fno.lfsize = sizeof lfn;
#endif
本文档为【FatFs通用FAT文件系统模块中文手册】,请使用软件OFFICE或WPS软件打开。作品中的文字与图均可以修改和编辑,
图片更改请在作品中右键图片并更换,文字修改请直接点击文字进行修改,也可以新增和删除文档中的内容。
该文档来自用户分享,如有侵权行为请发邮件ishare@vip.sina.com联系网站客服,我们会及时删除。
[版权声明] 本站所有资料为用户分享产生,若发现您的权利被侵害,请联系客服邮件isharekefu@iask.cn,我们尽快处理。
本作品所展示的图片、画像、字体、音乐的版权可能需版权方额外授权,请谨慎使用。
网站提供的党政主题相关内容(国旗、国徽、党徽..)目的在于配合国家政策宣传,仅限个人学习分享使用,禁止用于任何广告和商用目的。