FATFS文件系统接口函数

体发生变化后，访问第一个文件时 FATFS 被初始化。其他应用程序不能改变结构的
任何成员变量。
typedef struct {
BYTE fs_type;
/* FAT 子类型，一般在 mount 时用，置 0 表示未挂载*/
BYTE drv;
/* 物理驱动器号，一般为 0*/
BYTE csize;
/*每个簇的扇区数目(1,2,4...128) */
} FIL;
3. DIR 结构，目录对象结构体。所在文件 ff.h。
DIR 结构体被 f_opendir，f_readdir 函数用来读取工作区目录。其他应用程序不
能改变其成员变量。
typedef struct {
FATFS* fs;
/* 所在的文件系统指针*/
WORD id;
/* 所在的文件系统挂载编号*/
函数描述 在 f_open 函数执行成功后，文件对象开始有效。文件对象用于随后指定文件的
读写函数。使用 f_close 函数来关闭打开的文件对象。如果更改的文件未被关闭，文 件数据可能崩溃。
在使用任何文件函数前，必须使用 f_mount 函数在逻辑驱动器上注册一个工作 区（文件系统对象）。除 f_fdisk 函数外，所有的 API 函数需在完成此过程后工作。
DWORD database; DWORD winsect; BYTE win[_MAX_SS]; } FATFS;
/* 数据目录起始扇区*/ /* 当前缓冲区中存储的扇区号*/ /* 单个扇区缓存， FAT (and Data on tiny cfg) */
2. FIL 结构，文件对象结构。所在文件 ff.h。
WORD n_rootdir;
/* 根目录区入口(目录项)的个数(用于 FAT12/16)*/
#if _MAX_SS != 512
WORD ssize;
/* 每扇区的字节数(用于扇区大于 512Byte 的 flash) */
Байду номын сангаас
#endif
#if _FS_REENTRANT
_SYNC_t sobj;
/* 允许重入，即定义同步对象，用在 tiny 中*/
/* 读字节数 */
UINT* ByteRead
/*读字节数变量指针 */
);
参数说明 FileObject Buffer ByteToRead ByteRead
打开的文件对象指针 存储读取数据缓冲区指针 在 UINT 范围内，读取的字节数 返回读取字节数的无符号整型变量指针。这个值在函数调用后 有效，与函数执行结果无关。
/* 允许相对路径时用，存储当前目录起始簇(0:root)*/
#endif
DWORD n_fatent;
/* FAT 目录数(簇的数目 + 2)*/
DWORD fsize;
/* 每个 FAT 所占扇区*/
DWORD fatbase;
/* FAT 起始扇区*/
DWORD dirbase;
/* 根目录起始扇区(FAT32:Cluster#) */
要创建的目标文件结构体指针。 指定创建或打开以空终止的字符串文件名指针 指定访问或打开文件的模式类型。可以是以下标志的组合。
值
描述
FA_READ
指定读访问对象。可以从文件读取数据。与 FA_WRITE 组合为 读写访问。
FA_WRITE
指定写访问对象。可以向文件写入数据。与 FA_READ 组合为 读写访问。
函数执行成功 指定的驱动器号非法
函数描述 f_mount 函数在 FatFS 模块中注册/注销一个工作区。在使用其他文件函数前工
作区必须先使用这个函数给定每个卷。指定一个 NULL 到 FileSystemObject,注销一个 工作区,然后工作区将被废弃。
不管驱动器处于何种状态，此函数总是返回成功。在此函数中不发生媒体访问。 它只初始化给定的工作区域并且注册其地址到内部表。在 f_mount 函数执行或者媒 体改变后，在第一次文件访问时执行卷安装过程。
FA_CREATE_ALWAYS 创建一个新文件。如果文件存在，将被删节和复写。
函数返回值 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_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES
函数返回值 FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT,
FR_TIMEOUT
函数描述 文件对象的文件指针随着读取字节数的增加而增加。在函数执行成功后，*ByteRead 应该是否检测到了文件结尾。在*ByteRead < ByteToRead 情况下，意味着在读操作 期间，读写指针到达了文件尾。
*/
#if _USE_LFN
WCHAR* lfn;
/* 长文件名缓冲区指针 */
WORD lfn_idx;
/* 最后匹配的长文件名索引号 (0xFFFF:No LFN) */
#endif
} DIR;
二、 FATFS 文件系统 API 参考
1. f_mount 函数，主要用来在 FatFS 模块中注册/注销工作区。
BYTE n_fats;
/* 文件分配表的数目(1,2) ，FAT 文件系统依次为：引导
扇区、两个文件分配表、根目录区和数据区*/
BYTE wflag;
/*标记文件是否被改动过，为 1 时要回写*/
BYTE fsi_flag;
/* 标记文件系统信息是否被改动过，为 1 时要回写*/
WORD id;
/* 文件系统挂载 ID */
5. f_write 函数，写数据到文件
FRESULT f_write ( FIL* FileObject, const void* Buffer, UINT ByteToWrite, UINT* ByteWritten
);
/*文件对象结构体指针*/ /*写入数据缓冲区指针*/ /* 写字节数 */ /*写字节数变量指针*/
FATFS* fs;
/* 所在的文件系统指针*/
WORD id;
/* 所在的文件系统挂载编号*/
BYTE flag;
/* 文件状态*/
BYTE pad1;
/* 不知道含义，也未见程序使用*/
DWORD fptr;
/* 文件读写指针*/
DWORD fsize;
/* 文件大小*/
DWORD sclust;
/* 文件起始簇(fsize=0 时为 0) */
DWORD clust;
/* 当前簇*/
DWORD dsect;
/* 当前数据扇区*/
#if !_FS_READONLY
DWORD dir_sect;
/* 包含目录项的扇区 */
BYTE* dir_ptr;
/* 目录入口指针 */
#endif
#if _USE_FASTSEEK
FR_TIMEOUT
函数描述 文件对象的文件指针随着写入字节数的增加而增加。在函数执行成功后，
*ByteWrite 应该是否检测到了文件结尾。当*ByteWrite < ByteToWrite 时，意味着在 写操作期间卷满了。当卷满或接近满时，函数可能会花费一些时间。
当_FS_READONLY == 0 时此函数可用。
6. f_lseek 函数 FRESULT f_lseek ( FIL* FileObject, DWORD Offset );
DWORD* cltbl;
/*指向簇链接映射表的指针*/ (Nulled on file open) */
#endif
#if _FS_SHARE
UINT lockid;
/* 文件锁 ID */
#endif
#if !_FS_TINY
BYTE buf[_MAX_SS]; /* 数据读写缓冲区*/
#endif
FATFS 文件系统主要结构体及接口函数说明
一、 类型，结构体定义
1. FATFS 结构，文件系统对象结构体，所在文件 ff.h。
FATFS 结构(文件系统对象)用来保存独立逻辑驱动器动态工作区域。这个结构
由应用程序给定，使用 f_mount 函数注册/注销 FatFs 模块。在执行 f_mount 或媒
2. f_open 函数,此函数的功能是创建一个将要访问的文件对象。
FRESULT f_open (
FIL* FileObject,
/* 空目标文件结构体指针*/
const TCHAR* FileName,
/* 文件名指针 */
BYTE ModeFlags );
/* 文件打开模式标志 */
参数说明 FileObject FileName ModeFlags
注意，当_FS_READONLY == 1 时，模式标志 FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW 和 FA_OPEN_ALWAYS 不可用。
3. f_close 函数,此函数的功能是关闭一个打开的文件。
FRESULT f_close (
FIL* FileObject,
FRESULT f_mount(
BYTE Drive,
/*逻辑驱动器号*/
FATFS* FileSystemObject
/*工作区域指针*/
};
参数说明
Drive
注册/注销工作区域的逻辑驱动器号（0~9）
FileSystemObject 被注册的工作区域（文件系统目标）指针。
函数返回值 FR_OK (0) FR_INVALID_DRIVE
WORD index;
/* 当前读写目录索引号 */
DWORD sclust;
/* 目录表起始簇 ，0 表示根目录*/
DWORD clust;
/* 当前簇 */
DWORD sect;
/* 当前扇区 */
BYTE* dir;
/* 当前文件(SFN,短文件名)入口指针 */
BYTE* fn;
/* 文件指针 (in/out) {file[8],ext[3],status[1]}
/* 文件对象结构体指针*/
);
参数说明 FileObject
将要关闭的已打开文件指针
函数返回值 FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT,
FR_TIMEOUT
函数描述 f_close 函数关闭一个打开的文件对象。如果有任何数据写入到了文件，文件的
缓冲区信息被写回到磁盘。在 f_close 函数执行成功后，文件对象不再有效，并被丢 弃。
4. f_read 函数，从文件读取数据
FRESULT f_read (
FIL* FileObject,
/*文件对象结构体指针*/
void* Buffer,
/* 读取数据缓冲区指针 */
UINT ByteToRead,
#endif
#if !_FS_READONLY
DWORD last_clust;
/* 最后一个被分配的簇*/
DWORD free_clust; /* 空闲簇数目*/
DWORD fsi_sector;
/* 存放 fsinfo 的扇区(用于 FAT32) */
#endif
#if _FS_RPATH
DWORD cdir;
参数说明 FileObject Buffer ByteToWrite ByteWrite
打开的文件对象指针 存储写入数据缓冲区指针 在 UINT 范围内，写入的字节数 返回写入字节数的无符号整型变量指针。这个值在函数调用后 有效，与函数执行结果无关。
函数返回值 FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT,
FIL 结构（文件对象）用来保存打开文件的状态。它由 f_open 函数创建，由 f_close
函数废弃。除 cltbl 外，其成员不能被其他应用程序改变。注意：在 non-tiny 配置情
况下，在结构体中定义了一个扇区缓冲区，因此 FIL 结构不能够被定义为自动变量。
typedef struct {
FA_OPEN_EXISTING 打开文件。如果文件不存在，函数返回失败。（默认模式）
FA_OPEN_ALWAYS
如果存在打开文件。如果文件不存在，创建一个新文件。在使 用此模式打开文件后，使用 f_lseek 函数，追加数据到文件。
FA_CREATE_NEW
创建一个新文件。如果文件存在，函数执行失败，并返回 FR_EXIST 值。