FATFS文件系统常用指令

FATFS文件系统常用指令

一、说明

以官网下载的 ff12b 版本为例，定义变量举例。

FRESULT res;  /* 文件操作结果 */
FATFS fs; /* FatFs文件系统对象 */
FIL   fp; /* 文件对象 */
UINT br; /* 文件成功写入数量 */
UINT bw; /* 文件成功读取数量 */
BYTE read_buffer[_MAX_SS]= {0}; /* 读缓冲区 */
BYTE write_buf[] = "hello";/* 写缓冲区*/

二、指令

1、f_mkfs

在驱动器上创建一个文件系统

FRESULT f_mkfs (
	const TCHAR* path,	/* 逻辑驱动器号 */
	BYTE opt,			/* 格式选项 */
	DWORD au,			/* 分配单元[字节]的大小 */
	void* work,			/* 指向工作缓冲区的指针 */
	UINT len			/* 工作缓冲器大小 */
)

例：

//在逻辑驱动器0上创建一个格式为FAT32的文件系统，缓冲区的大小为_MAX_SS = 4096
res = f_mkfs("0:",FM_FAT32,0,read_buffer,sizeof(read_buffer));

f_mkfs 函数当 _FS_READOLNY == 0 并且 _USE_MKFS == 1 时可用。
f_mkfs 函数在驱动器中创建一个 FAT 文件系统。对于可移动媒介，有两种分区规则： FDISK 和 SFD ，通过参数PartitioningRule 选择。 FDISK 格式在大多数情况下被推荐使用。该函数当前不支持多分区，因此，物理驱动器上已存在的分区将被删除，并且重新创建一个占据全部磁盘空间的新分区。

根据 Microsoft 发布的 FAT 规范， FAT 分类： FAT12/FAT16/FAT32 ，由驱动器上的簇数决定。因此，选择哪种 FAT 分类，取决于卷大小和指定的簇大小。簇大小影响文件系统的性能，并且大簇会提高性能。

2、f_mount

文件挂载/取消挂载指令。FatFs 模块上注册 / 注销一个工作区。 在使用任何其他文件函数之前，必须使用该函数为每个卷注册一个工作区。要注销一个工作区，只要指定 FileSystemObject 为 NULL 即可，然后该工作区可以被丢弃。

FRESULT f_mount (
	FATFS* fs,			/* 指向文件系统对象的指针(NULL:卸载)*/
	const TCHAR* path,	/* 要挂载/卸载的逻辑驱动器号 */
	BYTE opt			/* 模式选项0:不挂载(延迟挂载)，1:立即挂载 */
)

例：

res = f_mount(fs,"0:",1);  //挂载
res = f_mount(NULL,"0:",1);  //取消挂载 

3、f_open

创建 / 打开一个用于访问文件的文件对象。

FRESULT f_open (
	FIL* fp,			/* 指向空白文件对象的指针 */
	const TCHAR* path,	/* 指向文件名的指针 */
	BYTE mode			/* 访问模式和文件打开模式标志 */
)

例：

//打开读写权限，创建一个新文件。如果文件已存在，则它将被截断并覆盖。
res = f_open(&fp, "0:test.txt", FA_READ|FA_WRITE|FA_CREATE_ALWAYS);  

模式	描述
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 是无效的。

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

4、f_close

关闭一个打开的文件

FRESULT f_close (
	FIL* fp		/* 指向要关闭的文件对象的指针 */
)

例：

res = f_close(&fp);  //关闭fp文件。

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

5、f_read

从一个文件读取数据

从一个文件读取数据
FRESULT f_read (
	FIL* fp, 	/* 指向文件对象的指针 */
	void* buff,	/* 数据缓冲区指针 */
	UINT btr,	/* 要读取的字节数*/
	UINT* br	/* 指针指向读取的字节数 */
)

例：

//将fp文件里的内容读取到read_buf缓冲区，返回读取字节数br
res = f_read(&fp, read_buf, sizeof(write_buf), &br);

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

6、f_write

写入数据到一个文件

FRESULT f_write (
	FIL* fp,			/* 指向文件对象的指针 */
	const void* buff,	/* 指向要写入的数据的指针 */
	UINT btw,			/* 要写入的字节数 */
	UINT* bw			/* 指向写入的字节数的指针 */
)

//write_buf数组的内容写入到fp文件中，返回写入字节数bw
res = f_write(&fp, write_buf,  sizeof(write_buf), &bw);

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

7、f_lseek

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

FRESULT f_lseek (
	FIL* fp,		/* 指向文件对象的指针 */
	FSIZE_t ofs		/* 文件指针从文件的顶部 */
)

例：

f_lseek(&Fp, 0); // 读/写指针偏移0个字节

8、f_tell

获取当前读/写指针，函数原型是FIL结构体中成员变量fptr。

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

例：

uint32_t Drv_FatfsTell(void)
{
	return f_tell(&Fp); //返回指针
}

9、f_size

获取一个文件大小，函数原型是FIl结构体成员_FDID obj结构体成员objsize

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

例：

uint32_t Drv_FatfsSize(void)
{	
	return f_size(&Fp); //返回指针
}

10、f_opendir
11、f_readdir
f_opendir（打开一个目录）

FRESULT f_opendir (
	DIR* dp,			/* 要创建的目录对象的指针 */
	const TCHAR* path	/* 指向目录路径的指针 */
)

f_readdir（读取目录项 ）

FRESULT f_readdir (
	DIR* dp,			/* 指向开目录对象的指针 */
	FILINFO* fno		/* 返回文件信息的指针 */
)

两者配合使用，可以遍历文件，读取出文件路径和文件名。

例：

void Drv_FatfsReaddir(void)
{
	DIR dir;  			//目录
	FILINFO fileinfo;	//文件信息
	FRESULT Res; /* 返回状态值 */
	Res = f_opendir(&dir, (const TCHAR*)DriveNumber);
	while(1)
	{
		Res = f_readdir(&dir, &fileinfo);
		if (Res != FR_OK || fileinfo.fname[0] == 0) break;
		printf("%s", DriveNumber);//打印路径
		printf("%s \r\n", fileinfo.fname);//打印文件名	
	}
}

12、f_getfree

获取空闲簇的数目 ，也就是获取出空闲扇区的数量，同时也可过去总扇区数量。

FRESULT f_getfree (
	const TCHAR* path,	/* 逻辑驱动器号的路径名 */
	DWORD* nclst,		/* 指向一个变量的指针，该变量返回空闲集群的数量 */
	FATFS** fatfs		/* 返回指向相应文件系统对象的指针 */
)

例：

uint32_t Drv_FatfsGetfree(void)
{
	FRESULT Res; /* 返回状态值 */
	FATFS *Fs1;
	uint32_t FreClust=0; //空闲集群的数量
	uint32_t FreSect=0;  //空闲扇区数
//	uint32_t TotSect=0;  //总扇区数
	Res = f_getfree(DriveNumber, (DWORD*)&FreClust, &Fs1);
	if(Res == FR_OK)
	{
		//TotSect = (Fs1->n_fatent - 2) * Fs1->csize; //得到总扇区数
		FreSect = FreClust * Fs1->csize;			//得到空闲扇区数	
		return FreSect;  //返回空闲扇区数
	}
	return 0;
}

三、FatFs 提供的操作指令函数API总预览

f_mount - 注册/注销一个工作区域（Work Area）

f_open - 打开/创建一个文件f_close - 关闭一个文件

f_read - 读文件f_write - 写文件

f_lseek - 移动文件读/写指针

f_truncate - 截断文件

f_sync - 冲洗缓冲数据 Flush Cached Data

f_opendir - 打开一个目录

f_readdir - 读取目录条目

f_getfree - 获取空闲簇 Get Free Clusters

f_stat - 获取文件状态

f_mkdir - 创建一个目录

f_unlink - 删除一个文件或目录

f_chmod - 改变属性（Attribute）

f_utime - 改变时间戳（Timestamp）

f_rename - 重命名/移动一个文件或文件夹

f_mkfs - 在驱动器上创建一个文件系统

f_forward - 直接转移文件数据到一个数据流 Forward file data to the stream directly

f_gets - 读一个字符串

f_putc - 写一个字符

f_puts - 写一个字符串

f_printf - 写一个格式化的字符磁盘I/O接口

f_tell - 获取当前读/写指针

f_eof - 测试一个文件是否到达文件末尾

f_size - 获取一个文件大小

f_error - 测试一个文件是否出错

三、文档引用链接

链接: https://blog.csdn.net/limanjihe/article/details/52302711.