FATFS文件系统应用程序手册(中文版)

FATFS-------基于R0.009A版本函数名描述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测试一个文件是否出错一．应用程序1．f_mount在FatFs模块上注册/注销一个工作区(文件系统对象)。FRESULTf_mount(BYTEDrive,/*逻辑驱动器号*/FATFS*FileSystemObject/*工作区指针*/);参数Drive注册/注销工作区的逻辑驱动器号(0-9)。FileSystemObject工作区(文件系统对象)指针。返回值FR_OK(0)函数成功。FR_INVALID_DRIVE驱动器号无效描述f_mount函数在FatFs模块上注册/注销一个工作区。在使用任何其他文件函数之前，必须使用该函数为每个卷注册一个工作区。要注销一个工作区，只要指定FileSystemObject为NULL即可，然后该工作区可以被丢弃。该函数只初始化给定的工作区，以及将该工作区的地址注册到内部表中，不访问磁盘I/O层。卷安装过程是在f_mount函数执行后或存储介质改变后的第一次文件访问时完成的。2.f_open创建/打开一个用于访问文件的文件对象FRESULTf_open(FIL*FileObject,/*空白文件对象结构指针*/constXCHAR*FileName,/*文件名指针*/BYTEModeFlags/*模式标志*/);参数FileObject将被创建的文件对象结构的指针。FileNameNULL结尾的字符串指针，该字符串指定了将被创建或打开的文件名。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函数为驱动器注册一个工作区。只有这样，其他文件函数才能正常工作。示例(文件拷贝)voidmain(void){FATFSfs[2];/*逻辑驱动器的工作区(文件系统对象)*/FILfsrc,fdst;/*文件对象*/BYTEbuffer[4096];/*文件拷贝缓冲区*/FRESULTres;/*FatFs函数公共结果代码*/UINTbr,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||bwbr)break;/*磁盘满错误*/}/*关闭打开的文件*/f_close(&fsrc);f_close(&fdst);/*注销工作区(在废弃前)*/f_mount(0,NULL);f_mount(1,NULL);}3．f_close关闭一个打开的文件FRESULTf_close(FIL*FileObject/*文件对象结构的指针*/);参数FileObject指向将被关闭的已打开的文件对象结构的指针。返回值FR_OK(0)文件对象已被成功关闭。FR_DISK_ERR由于底层磁盘I/O函数中的错误，而导致该函数失败。FR_INT_ERR由于一个错误的FAT结构或一个内部错误，而导致该函数失败。FR_NOT_READY由于驱动器中没有存储介质或任何其他原因，而导致磁盘驱动器无法工作。FR_INVALID_OBJECT文件对象无效。描述f_close函数关闭一个打开的文件对象。无论向文件写入任何数据，文件的缓存信息都将被写回到磁盘。该函数执行成功后，文件对象不再有效，并且可以被丢弃。如果文件对象是在只读模式下打开的，不需要使用该函数，也能被丢弃。4．f_read从一个文件读取数据FRESULTf_read(FIL*FileObject,/*文件对象结构的指针*/void*Buffer,/*存储读取数据的缓冲区的指针*/UINTByteToRead,/*要读取的字节数*/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来检测文件是否结束，如果*ByteReadByteToRead，则表示读/写指针到达了文件结束位置。5．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，则意味着该卷已满。6．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不是所期望的值，则发生了下列情况之一。（1）.文件结束。指定的offset被限制在文件大小内，因为文件已被以只读模式打开。（2）.磁盘满。卷上没有足够的空闲空间去扩展文件大小。示例/*移动文件读/写指针到相对于文件起始处偏移为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);/*簇预分配(为了防止在流