f_write写入数据到一个文件
FRESULTf_write(
FIL*FileObject,/*文件对象结构的指针*/
constvoid*Buffer,/*存储写入数据的缓冲区的指针*/
UINTByteToWrite,/*要写入的字节数*/
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
移动一个打开的文件对象的文件读/写指针。
也可以被用来扩展文件大小(簇预分配)。
FRESULTf_lseek(
FIL*FileObject,/*文件对象结构指针*/
DWORDOffset/*文件字节偏移*/
);
参数
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不是所期望的值,则发生了下列情况之一。
∙文件结束。
指定的offset被钳在文件大小,因为文件已被以只读模式打开。
∙磁盘满。
卷上没有足够的空闲空间去扩展文件大小。
例子
/*移动文件读/写指针到相对于文件起始处偏移为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);
f_truncate
截断文件大小
FRESULTf_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
冲洗一个写文件的缓存信息
FRESULTf_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
打开一个目录
FRESULTf_opendir(
DIR*DirObject,/*空白目录对象结构的指针*/
constXCHAR*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函数打开一个已存在的目录,并为后续的调用创建一个目录对象。
该目录对象结构可以在任何时候不经任何步骤而被丢弃。
f_readdir
读取目录项
FRESULTf_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代码的字符,则一个空字符串将被返回,但是这不是UnicodeAPI配置的情况。
当lfname是一个空字符串时,没有LFN的任何数据被返回。
当对象没有LFN时,任何小型大写字母可以被包含在SFN中。
当相对路径功能被使能(_FS_RPATH==1)时,"."和".."目录项不会被过滤掉,并且它将出现在读目录项中。
例子
FRESULTscan_files(char*path)
{
FRESULTres;
FILINFOfno;
DIRdir;
inti;
char*fn;
#if_USE_LFN
staticcharlfn[_MAX_LFN*(_DF1S?
2:
1)+1];
fno.lfname=lfn;
fno.lfsize=sizeof(lfn);
#endif
res=f_opendir(&dir,path);
if(res==FR_OK){
i=strlen(path);
for(;;){
res=f_readdir(&dir,&fno);
if(res!
=FR_OK||fno.fname[0]==0)break;
if(fno.fname[0]=='.')continue;
#if_USE_LFN
fn=*fno.lfname?
fno.lfname:
fno.fname;
#else
fn=fno.fname;
#endif
if(fno.fattrib&AM_DIR){
sprintf(&path[i],"/%s",fn);
res=scan_files(path);
if(res!
=FR_OK)break;
path[i]=0;
}else{
printf("%s/%s\n",path,fn);
}
}
}
returnres;
}
f_getfree
获取空闲簇的数目
FRESULTf_getfree(
constXCHAR*Path,/*驱动器的根目录*/
DWORD*Clusters,/*存储空闲簇数目变量的指针*/
FATFS**FileSystemObject/*文件系统对象指针的指针*/
);
参数
Path'\0'结尾的字符串指针,该字符串指定了逻辑驱动器的目录。
Clusters存储空闲簇数目的DWORD变量的指针。
FileSystemObject相应文件系统对象指针的指针。
返回值
FR_OK(0)函数成功。
*Clusters表示空闲簇的数目,并且*FileSystemObject指向文件系统对象。
FR_INVALID_DRIVE驱动器号无效。
FR_NOT_READY由于驱动器中没有存储介质或任何其他原因,而导致磁盘驱动器无法工作。
FR_DISK_ERR由于底层磁盘I/O函数中的错误,而导致该函数失败。
FR_INT_ERR由于一个错误的FAT结构或一个内部错误,而导致该函数失败。
FR_NOT_ENABLED逻辑驱动器没有工作区。
FR_NO_FILESYSTEM磁盘上没有有效的FAT卷。
描述
f_getfree函数当_FS_READONLY==0并且_FS_MINIMIZE==0时有效。
f_getfree函数获取驱动器上空闲簇的数目。
文件系统对象中的成员csize是每簇中的扇区数,因此,以扇区为单位的空闲空间可以被计算出来。
当FAT32卷上的FSInfo结构不同步时,该函数返回一个错误的空闲簇计数。
列子
FATFS*fs;
DWORDfre_clust,fre_sect,tot_sect;
/*Getdriveinformationandfreeclusters*/
res=f_getfree("/",&fre_clust,&fs);
if(res)die(res);
/*Gettotalsectorsandfreesecto