FATFS-API

FATFS文件系统主要结构体及接口函数说明一、类型，结构体定义1.FATFS结构，文件系统对象结构体，所在文件ff.h。FATFS结构(文件系统对象)用来保存独立逻辑驱动器动态工作区域。这个结构由应用程序给定，使用f_mount函数注册/注销FatFs模块。在执行f_mount或媒体发生变化后，访问第一个文件时FATFS被初始化。其他应用程序不能改变结构的任何成员变量。typedefstruct{BYTEfs_type;/*FAT子类型，一般在mount时用，置0表示未挂载*/BYTEdrv;/*物理驱动器号，一般为0*/BYTEcsize;/*每个簇的扇区数目(1,2,4...128)*/BYTEn_fats;/*文件分配表的数目(1,2)，FAT文件系统依次为：引导扇区、两个文件分配表、根目录区和数据区*/BYTEwflag;/*标记文件是否被改动过，为1时要回写*/BYTEfsi_flag;/*标记文件系统信息是否被改动过，为1时要回写*/WORDid;/*文件系统挂载ID*/WORDn_rootdir;/*根目录区入口(目录项)的个数(用于FAT12/16)*/#if_MAX_SS!=512WORDssize;/*每扇区的字节数(用于扇区大于512Byte的flash)*/#endif#if_FS_REENTRANT_SYNC_tsobj;/*允许重入，即定义同步对象，用在tiny中*/#endif#if!_FS_READONLYDWORDlast_clust;/*最后一个被分配的簇*/DWORDfree_clust;/*空闲簇数目*/DWORDfsi_sector;/*存放fsinfo的扇区(用于FAT32)*/#endif#if_FS_RPATHDWORDcdir;/*允许相对路径时用，存储当前目录起始簇(0:root)*/#endifDWORDn_fatent;/*FAT目录数(簇的数目+2)*/DWORDfsize;/*每个FAT所占扇区*/DWORDfatbase;/*FAT起始扇区*/DWORDdirbase;/*根目录起始扇区(FAT32:Cluster#)*/DWORDdatabase;/*数据目录起始扇区*/DWORDwinsect;/*当前缓冲区中存储的扇区号*/BYTEwin[_MAX_SS];/*单个扇区缓存，FAT(andDataontinycfg)*/}FATFS;2.FIL结构，文件对象结构。所在文件ff.h。FIL结构（文件对象）用来保存打开文件的状态。它由f_open函数创建，由f_close函数废弃。除cltbl外，其成员不能被其他应用程序改变。注意：在non-tiny配置情况下，在结构体中定义了一个扇区缓冲区，因此FIL结构不能够被定义为自动变量。typedefstruct{FATFS*fs;/*所在的文件系统指针*/WORDid;/*所在的文件系统挂载编号*/BYTEflag;/*文件状态*/BYTEpad1;/*不知道含义，也未见程序使用*/DWORDfptr;/*文件读写指针*/DWORDfsize;/*文件大小*/DWORDsclust;/*文件起始簇(fsize=0时为0)*/DWORDclust;/*当前簇*/DWORDdsect;/*当前数据扇区*/#if!_FS_READONLYDWORDdir_sect;/*包含目录项的扇区*/BYTE*dir_ptr;/*目录入口指针*/#endif#if_USE_FASTSEEKDWORD*cltbl;/*指向簇链接映射表的指针*/(Nulledonfileopen)*/#endif#if_FS_SHAREUINTlockid;/*文件锁ID*/#endif#if!_FS_TINYBYTEbuf[_MAX_SS];/*数据读写缓冲区*/#endif}FIL;3.DIR结构，目录对象结构体。所在文件ff.h。DIR结构体被f_opendir，f_readdir函数用来读取工作区目录。其他应用程序不能改变其成员变量。typedefstruct{FATFS*fs;/*所在的文件系统指针*/WORDid;/*所在的文件系统挂载编号*/WORDindex;/*当前读写目录索引号*/DWORDsclust;/*目录表起始簇，0表示根目录*/DWORDclust;/*当前簇*/DWORDsect;/*当前扇区*/BYTE*dir;/*当前文件(SFN,短文件名)入口指针*/BYTE*fn;/*文件指针(in/out){file[8],ext[3],status[1]}*/#if_USE_LFNWCHAR*lfn;/*长文件名缓冲区指针*/WORDlfn_idx;/*最后匹配的长文件名索引号(0xFFFF:NoLFN)*/#endif}DIR;二、FATFS文件系统API参考1.f_mount函数，主要用来在FatFS模块中注册/注销工作区。FRESULTf_mount(BYTEDrive,/*逻辑驱动器号*/FATFS*FileSystemObject/*工作区域指针*/};参数说明Drive注册/注销工作区域的逻辑驱动器号（0~9）FileSystemObject被注册的工作区域（文件系统目标）指针。函数返回值FR_OK(0)函数执行成功FR_INVALID_DRIVE指定的驱动器号非法函数描述f_mount函数在FatFS模块中注册/注销一个工作区。在使用其他文件函数前工作区必须先使用这个函数给定每个卷。指定一个NULL到FileSystemObject,注销一个工作区,然后工作区将被废弃。不管驱动器处于何种状态，此函数总是返回成功。在此函数中不发生媒体访问。它只初始化给定的工作区域并且注册其地址到内部表。在f_mount函数执行或者媒体改变后，在第一次文件访问时执行卷安装过程。2.f_open函数,此函数的功能是创建一个将要访问的文件对象。FRESULTf_open(FIL*FileObject,/*空目标文件结构体指针*/constTCHAR*FileName,/*文件名指针*/BYTEModeFlags/*文件打开模式标志*/);参数说明FileObject要创建的目标文件结构体指针。FileName指定创建或打开以空终止的字符串文件名指针ModeFlags指定访问或打开文件的模式类型。可以是以下标志的组合。值描述FA_READ指定读访问对象。可以从文件读取数据。与FA_WRITE组合为读写访问。FA_WRITE指定写访问对象。可以向文件写入数据。与FA_READ组合为读写访问。FA_OPEN_EXISTING打开文件。如果文件不存在，函数返回失败。（默认模式）FA_OPEN_ALWAYS如果存在打开文件。如果文件不存在，创建一个新文件。在使用此模式打开文件后，使用f_lseek函数，追加数据到文件。FA_CREATE_NEW创建一个新文件。如果文件存在，函数执行失败，并返回FR_EXIST值。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函数描述在f_open函数执行成功后，文件对象开始有效。文件对象用于随后指定文件的读写函数。使用f_close函数来关闭打开的文件对象。如果更改的文件未被关闭，文件数据可能崩溃。在使用任何文件函数前，必须使用f_mount函数在逻辑驱动器上注册一个工作区（文件系统对象）。除f_fdisk函数外，所有的API函数需在完成此过程后工作。注意，当_FS_READONLY==1时，模式标志FA_WRITE,FA_CREATE_ALWAYS,FA_CREATE_NEW和FA_OPEN_ALWAYS不可用。3.f_close函数,此函数的功能是关闭一个打开的文件。FRESULTf_close(FIL*FileObject,/*文件对象结构体指针*/);参数说明FileObject将要关闭的已打开文件指针函数返回值FR_OK,FR_DISK_ERR,FR_INT_ERR,FR_NOT_READY,FR_INVALID_OBJECT,FR_TIMEOUT函数描述f_close函数关闭一个打开的文件对象。如果有任何数据写入到了文件，文件的缓冲区信息被写回到磁盘。在f_close函数执行成功后，文件对象不再有效，并被丢弃。4.f_read函数，从文件读取数据FRESULTf_read(FIL*FileObject,/*文件对象结构体指针*/void*Buffer,/*读取数据缓冲区指针*/UINTByteToRead,/*读字节数*/UINT*ByteRead/*读字节数变量指针*/);参数说明FileObject打开的文件对象指针Buffer存储读取数据缓冲区指针ByteToRead在UINT范围内，读取的字节数ByteRead返回读取字节数的无符号整型变量指针。这个值在函数调用后有效，与函数执行结果无关。函数返回值FR_OK,FR_DISK_ERR,FR_INT_ERR,FR_NOT_READY,FR_INVALID_OBJECT,FR_TIMEOUT函数描述文件对象的文件指针随着读取字节数的增加而增加。在函数执行成功后，*ByteRead应该是否检测到了文件结尾。在*ByteReadByteToRead情况下，意味着在读操作期间，读写指针到达了文件尾。5.f_write函数，写数据到文件FRESULTf_write(FIL*FileObject,/*文件对象结构体指针*/constvoid*Buffer,/*写入数据缓冲区指针*/UINTByteToWrite,/*写字节数*/UINT*ByteWritten/*写字节数变量指针*/);参数说明FileObject打开的文件对象指针Buffer存储写入数据缓冲区指针ByteToWrite在UINT范围内，写入的字节数ByteWrite返回写入字节数的无符号整型变量指针。这个值在函数调用后有效，与函数执行结果无关。函数返回值FR_OK,FR_DISK_ERR,FR_INT_ERR,FR_NOT_READY,FR_INVALID_OBJECT,FR_TIMEOUT函数描述文件对象的文件指针随着写入字节数的增加而增加。在函数执行成功后，*ByteWrite应该是否检测到了文件结尾。当*ByteWriteByteToWrite时，意味着在写操作期间卷满了。当卷满或接近满时，函数可能会花费一些时间。当_FS_READONLY==0时此函数可用。6.f_lseek函数FRESULTf_lseek(FIL*FileObject,/*文件对象结构体指针*/DWORDOffset/*文件偏移量(单位:字节)*/);参数说明FileObject打开的文件对象指针Offset相对文件开头的字节数函数返回值FR_OK,FR_DISK_ERR,FR_INT_ERR,FR_NOT_READY,FR_INVALID_OBJECT,FR_TIMEOUT函数描述f_lseek函数功能是移动一个打开文件的文件读写指针。偏移量可以被设定为唯一源自文件顶部。当一个超过文件大小的偏移量在写模式下被设置时，文件大小增加到偏移量大小但在扩展区域中的数据是不确定的。这适合快速创建一个大文件，快速的写文件。在f_lseek函数成功执行后，应该检查文件对象结构体成员变量fptr，以确定读写指针是否被正确地移动。在fptr不是预期值的情况下，可能发生以下两种情况。.文件结束。指定的偏移量被限制到文件大