FAFTS文件系统常用函数学习

一、FATFS文件系统基础知识

1.简介

文件系统可以从官网进行下载

官网地址：http://elm-chan.org/fsw/ff/00index_e.html

FATFS是一个完全免费开源的FAT 文件系统模块，FatFs模块是按照ANSI C（C89）编写的，并且与磁盘I / O层完全分开，它支持FATl2、FATl6 和FAT32，支持多个存储媒介，有独立的缓冲区，可以对多个文件进行读／写，并特别对8 位单片机和16 位单片机做了优化，。因此，它独立于平台。它可以并入资源有限的小型微控制器中，例如8051，PIC，AVR，ARM，Z80，RX等，具有良好的硬件平台独立性。

2.特征

• DOS / Windows兼容的FAT / exFAT文件系统。

• 平台无关。容易移植。

• 程序代码和工作区的占用空间非常小。

• 支持以下各种配置选项：

  • ANSI / OEM或Unicode中的长文件名。

  • exFAT文件系统，64位LBA和GPT可存储大量数据。

  • RTOS的线程安全。

  • 多个卷（物理驱动器和分区）。

  • 可变扇区大小。

  • 多个代码页，包括DBCS。

  • 只读，可选API，I / O缓冲区等

二、文件接口

1.f_open

函数作用：

f_open`函数打开一个文件，并创建一个文件对象。文件对象用于随后对文件的读/写操作以标识文件。访问文件的会话之后，应使用f_close函数关闭打开的文件。如果对文件进行了任何更改并且在关闭电源之前未关闭文件，则介质移除或重新安装或文件可能会折叠。

函数体：

FRESULT f_open（
  FIL * fp，            / * 指向文件对象结构的指针* / 
  const TCHAR * path，/ * 文件名* / 
  BYTE mode          / * 模式标志* /
）;

参数含义：

fp：指向空白文件对象结构的指针。

路径：指向以空值结尾的字符串的指针，该字符串指定要打开或创建的文件名。如：“0:message.txt"

模式：

举例：

2.f_close

函数作用：

f_close函数关闭一个打开的文件对象。如果文件已更改，则文件的缓存信息将写回到该卷。函数成功后，文件对象不再有效，可以将其丢弃。

函数体

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

3.f_read

函数作用：

该函数以读/写指针指向的文件偏移量开始从文件中读取数据。读/写指针随着读取的字节数而增加。函数成功后，应检查* br以检测文件结尾。如果* br < btr，则意味着在读操作期间读/写指针到达文件的末尾。

FRESULT f_read（
  FIL * fp，      / * [IN]文件对象* / 
  void * buff，   / * [OUT]存储读取数据的缓冲区* / 
  UINT btr，     / * [IN]要读取的字节数* / 
  UINT * br      / * [OUT]读取的字节数* / 
）；

4.f_write

函数作用 ：

函数开始在读/写指针指向的文件偏移量处向文件写入数据。读/写指针随着写入的字节数而增加。函数成功后，应检查bw以检测磁盘已满。如果bw<btw，则表示写入操作期间卷已满。当卷已满或接近满时，此功能可能需要一段时间。

函数体：

FRESULT f_write（
  FIL * fp，           / * [IN]指向文件对象结构的指针* / 
  const void * buff，/ * [IN]指向要写入的数据的指针* / 
  UINT btw，          / * [IN]要写入的字节数* / 
  UINT * bw           / * [OUT]指向变量的指针，以返回写入的字节数* /
）;

5.f_gets

函数作用：

读取操作将继续进行，直到存储了一个'\ n'，到达文件末尾或缓冲区中的len-1个字符为止。读取的字符串以'\ 0'终止。当没有字符要读取或在读取操作期间发生任何错误时，它将返回空指针。可以使用f_eof和f_error函数检查EOF和错误的状态。

函数体：

TCHAR * f_gets（
  TCHAR * buff，/ * [OUT]读取缓冲区* / 
  int len，      / * [IN]读取缓冲区的大小* / 
  FIL * fp       / * [IN]文件对象* /
）;

6.f_puts

函数作用：

成功写入字符串后，它将返回写入文件的字符编码单元数。当功能由于磁盘已满或任何错误而失败时，将返回EOF（-1）。

 函数体：

int f_puts（
  const TCHAR * str，/ * [IN]字符串* / 
  FIL * fp            / * [IN]文件对象* /
）;

读/写一个字符和读/写一个字符串大致相同，将要读/写入的变量定义成TCHAR即可。 

7.f_eof

函数作用：

f_eof函数测试文件的文件结尾，如果读/写指针已到达文件的结束则返回一个非零值; 否则返回零。

函数体：

int f_eof（
  FIL * fp    / * [IN]文件对象* /
）;

8.f_error

函数作用：

检测文件系统是否发生硬件错误，若未发生异常返回一个非零值，发生异常则返回0。

函数体：

int f_error (
  FIL* fp   /* [IN] File object */
);

 

整体应用：

/* Read a text file and display it */
​
FATFS FatFs;   /* Work area (filesystem object) for logical drive */
​
int main (void)
{
    FIL fil;        /* File object */
    char line[100]; /* Line buffer */
    FRESULT fr;     /* FatFs return code */
​
​
    /* Gives a work area to the default drive */
    f_mount(&FatFs, "", 0);
​
    /* Open a text file */
    fr = f_open(&fil, "message.txt", FA_READ);    
if (fr) return (int)fr;
​
    /* Read every line and display it */
    while (f_gets(line, sizeof line, &fil)) {
        printf(line);
    }
​
    /* Close the file */
    f_close(&fil);
​
    return 0;
}
/* Copy a file "file.bin" on the drive 1 to drive 0 */
​
int main (void)
{
    FATFS fs0, fs1;      /* Work area (filesystem object) for logical drives */
    FIL fsrc, fdst;      /* File objects */
    BYTE buffer[4096];   /* File copy buffer */
    FRESULT fr;          /* FatFs function common result code */
    UINT br, bw;         /* File read/write count */
​
​
    /* Gives work area to each logical drive */
    f_mount(&fs0, "0:", 0);
    f_mount(&fs1, "1:", 0);
​
    /* Open source file on the drive 1 */
    fr = f_open(&fsrc, "1:file.bin", FA_READ);
    if (fr) return (int)fr;
​
    /* Create destination file on the drive 0 */
    fr = f_open(&fdst, "0:file.bin", FA_WRITE | FA_CREATE_ALWAYS);
    if (fr) return (int)fr;
​
    /* Copy source to destination */
    for (;;) {
        f_read(&fsrc, buffer, sizeof buffer, &br);  /* Read a chunk of data from the source file */
        if (br == 0) break; /* error or eof */
        f_write(&fdst, buffer, br, &bw);            /* Write it to the destination file */
        if (bw < br) break; /* error or disk full */
    }
​
    /* Close open files */
    f_close(&fsrc);
    f_close(&fdst);
​
    /* Unregister work area prior to discard it */
    f_mount(0, "0:", 0);
    f_mount(0, "1:", 0);
​
    return (int)fr;
}

三、目录接口 

1.f_opendir

函数作用：

打开已存在的目录，并且为随后使用到的f_readdir函数创建一个目录对象。

函数体：

FRESULT f_opendir (
  DIR* dp,           /* [OUT] Pointer to the directory object structure */
  const TCHAR* path  /* [IN] Directory name */
);

2.f_clodedir

函数作用：

关闭一个打开的目录，当函数作用成功后，目录对象不再有效，可以被丢弃。

函数体：

FRESULT f_closedir (
  DIR* dp     /* [IN] Pointer to the directory object */
);

3.f_findfirst

函数作用：

在可以打开路径指定的目录后，它开始搜索目录中具有模式指定的匹配模式的项目。如果找到第一个项，则有关该项的信息将存储在文件信息结构fno 中。

函数体：

FRESULT f_findfirst (
  DIR* dp,              /* [OUT] Poninter to the directory object */
  FILINFO* fno,         /* [OUT] Pointer to the file information structure */
  const TCHAR* path,    /* [IN] Pointer to the directory name to be opened */
  const TCHAR* pattern  /* [IN] Pointer to the matching pattern string */
);

参数：

Dp：

指向空白目录对象的指针。

fno：

指向文件信息结构的指针，以存储有关找到的项的信息。

path：

指向指定要打开的目录名称的空终止字符串的指针。

mode:

指向 nul 终止字符串的指针，该字符串指定要搜索的名称匹配模式。它由后续函数f_findnext引用，因此字符串在连续函数调用时必须有效。

4.f_findnext

函数作用：

它继续搜索从上一个调用到f_findfirst或f_findnext函数。如果找到，有关该对象的信息将存储在文件信息结构中。如果没有要读取的项，则空字符串将返回到fno->fname= 中。

函数体：

FRESULT f_findnext (
  DIR* dp,              /* [IN] Poninter to the directory object */
  FILINFO* fno          /* [OUT] Pointer to the file information structure */
);

 

应用示例：

/* Search a directory for objects and display it */
 
void find_image_file (void)
{
    FRESULT fr;     /* Return value */
    DIR dj;         /* Directory object */
    FILINFO fno;    /* File information */
 
    fr = f_findfirst(&dj, &fno, "", "dsc*.jpg");  /* Start to search for photo files */
 
    while (fr == FR_OK && fno.fname[0]) {         /* Repeat while an item is found */
        printf("%s\n", fno.fname);                /* Print the object name */
        fr = f_findnext(&dj, &fno);               /* Search for next item */
    }
 
    f_closedir(&dj);
}

对于其中的f_findfirst函数调用，可以使用通配符匹配，包含通配符（？ 和 *）。例如，与任何字符匹配，* 匹配长度为零或更长的任何字符串，并且???* 匹配长度为 3 个字符或更长的任何字符串，例中dsc*.jpg就是指dsc开头，后面任意长度内容最后以.jpg结尾的字符串。

四、卷管理和系统配置接口

1.f_mount

函数作用：

FatFs 需要每个逻辑驱动器（FAT 卷） 的工作区 （ 文件系统对象 ）。在执行任何文件/目录操作之前，需要向逻辑驱动器的f_mount注册文件系统对象。此过程后，文件/目录 API 函数即可开始工作。某些卷管理函数f_mkfs，f_fdisk，f_setcp和文件，不需要文件系统对象。

f_mount将文件系统对象注册/取消注册到 FatF 模块，如下所示：

• 确定由路径指定的逻辑驱动器。
• 清除和取消注册卷的重新注册工作区（如果存在）。
• 如果fs不是 NULL，则清除新工作区并注册到卷。
• 如果指定了强制装载，则对卷执行卷装载过程。

如果逻辑驱动器上有任何打开的文件或目录对象，则该对象将因此函数而失效。

如果未指定强制安装（选择= 0），则无论物理驱动器状态如何，此功能始终成功。它只清除（去初始化）给定工作区，并将其地址注册到内部表，并且此函数中的物理驱动器没有活动。如果未初始化文件系统对象，则将在后续文件/直接函数上尝试卷装载过程。（延迟安装）卷装载进程，初始化相应的物理驱动器，查找其中 FAT 卷，然后初始化工作区，在后续文件/目录函数中执行，当以下任一条件为真时。

• 文件系统对象尚未初始化。它由函数f_mount初始化。
• 物理驱动器未初始化。它通过系统重置或介质移除而取消初始化。

如果强制安装（opt = 1） FR_NOT_READY失败，则表示文件系统对象已成功注册，但卷当前尚未准备好工作。将在后续文件/直接函数上尝试卷装载过程。

如果磁盘 I/O 层的实现缺少异步介质更改检测，则应用程序需要在每次介质更改后执行 f_mount函数以强制清除文件系统对象。

要取消注册工作区，指定一个 NULL 到fs，然后可以丢弃工作区。

简言之就是起到一个挂载作用。

函数体：

FRESULT f_mount (
  FATFS*       fs,    /* [IN] Filesystem object */
  const TCHAR* path,  /* [IN] Logical drive number */
  BYTE         opt    /* [IN] Initialization option */
);

参数：

fs：

指向要注册和清除的文件系统对象的指针。空指针取消注册文件系统对象。

path:

指向指定逻辑驱动器的空终止字符串的指针。不带驱动器号的字符串表示默认驱动器。

opt:

安装选项。0：现在不要装载（要装载在第一次访问卷上），1：强制装载卷以检查卷是否已准备好工作。

 

实例： 

int main (void)
{
    FATFS *fs;     /* Ponter to the filesystem object */
 
 
    fs = malloc(sizeof (FATFS));           /* Get work area for the volume */
    f_mount(fs, "", 0);                    /* Mount the default drive */
 
    f_open(...                             /* Here any file API can be used */
 
    ...
 
    f_mount(fs, "", 0);                    /* Re-mount the default drive to reinitialize the filesystem */
 
    ...
 
    f_mount(0, "", 0);                     /* Unmount the default drive */
    free(fs);                              /* Here the work area can be discarded */
 
    ...
}

2.f_mkfs

函数作用：该f_mkfs在逻辑驱动器上创建 FAT/exFAT 卷。

函数体：

FRESULT f_mkfs (
  const TCHAR*  path,  /* [IN] Logical drive number */
  const MKFS_PARM* opt,/* [IN] Format options */
  void*  work,         /* [-]  Working buffer */
  UINT  len            /* [IN] Size of working buffer */
);

参数：

• path:

指向空终止字符串的指针指定要格式化的逻辑驱动器。如果它没有驱动器号，则意味着指定默认驱动器。逻辑驱动器可能已装载，也可能未为格式进程安装。

• opt:

指定保存格式选项的结构。如果给定一个空指针，它将为函数提供默认值中的所有选项。格式选项结构有五个成员，描述如下：

• BYTE fmt:

指定 FAT 类型标志、FM_FAT、FM_FAT32、FM_EXFAT和位或这三个标记的组合FM_ANY。 FM_EXFAT启用 exFAT 时，将忽略此错误。这些标志指定要在卷上创建的 FAT 类型。如果指定了两种或两种类型，则将选择其中一种类型，这取决于卷大小和au_size。标志FM_SFD指定以 SFD 格式在驱动器上创建卷。默认值为FM_ANY。

• DWORD au_size:

指定以字节单位表示分配单位（cluter）的大小。有效值是扇区大小之间的 2 和 128 * 扇区大小的功率，包括 FAT/FAT32 卷和高达 16 MB 的 exFAT 卷。如果给出零（默认值）或任何无效值，则默认分配单位大小取决于使用的卷大小。

• UINT n_align:

指定卷数据区域（文件分配池，通常擦除闪存介质的块边界）在扇区单位中的对齐方式。此成员的有效值介于 1 和 32768 之间，包括 2。如果给出零（默认值）或任何无效值，则函数会从具有"一个函数"的较低层disk_ioctl大小。

• BYTE n_fat:

指定 FAT/FAT32 卷上的 FAT 副本数。此成员的有效值为 1 或 2。默认值 （0） 和任何 invaid 值给出 1。如果 FAT 类型为 exFAT，则此成员不起作用。

• UINT n_root:

指定 FAT 卷上的根目录条目数。此成员的有效值高达 32768，与扇区大小 / 32 对齐。默认值 （0） 和任何 invaid 值给出 512。如果 FAT 类型为 FAT32 或 exFAT，则此成员不起作用。

• work:

指向用于格式化过程的工作缓冲区的指针。当一个空指针被用FF_USE_LFN==3进行赋值时，函数将在此函数中为工作缓冲区获取内存块。

• len:

工作缓冲区的大小（以字节单位表示）。它至少需要FF_MAX_SS一点。大量工作缓冲区减少了驱动器的写入事务数，并且格式过程将快速完成。

实例：

/* Format default drive and create a file */
int main (void)
{
    FATFS fs;           /* Filesystem object */
    FIL fil;            /* File object */
    FRESULT res;        /* API result code */
    UINT bw;            /* Bytes written */
    BYTE work[FF_MAX_SS]; /* Work area (larger is better for processing time) */
 
 
    /* Format the default drive with default parameters */
    res = f_mkfs("", 0, work, sizeof work);
    if (res) ...
 
    /* Gives a work area to the default drive */
    f_mount(&fs, "", 0);
 
    /* Create a file as new */
    res = f_open(&fil, "hello.txt", FA_CREATE_NEW | FA_WRITE);
    if (res) ...
 
    /* Write a message */
    f_write(&fil, "Hello, World!\r\n", 15, &bw);
    if (bw != 15) ...
 
    /* Close the file */
    f_close(&fil);
 
    /* Unregister work area */
    f_mount(0, "", 0);
 
    ...

3.f_getfree

函数作用：

获取卷上可用的集群数。

函数体：

FRESULT f_getfree (
  const TCHAR* path,  /* [IN] Logical drive number */
  DWORD* nclst,       /* [OUT] Number of free clusters */
  FATFS** fatfs       /* [OUT] Corresponding filesystem object */
);

参数：

path:

指向指定逻辑驱动器的空终止字符串的指针。空字符串表示默认驱动器。

nclst:

指向DWORD 类型的指针以存储可用群集的数量。

fatfs:

指向指针，用于存储指向相应文件系统对象的指针。

实例：

    FATFS *fs;
    DWORD fre_clust, fre_sect, tot_sect;
 
 
    /* Get volume information and free clusters of drive 1 */
    res = f_getfree("1:", &fre_clust, &fs);
    if (res) die(res);
 
    /* Get total sectors and free sectors */
    tot_sect = (fs->n_fatent - 2) * fs->csize;
    fre_sect = fre_clust * fs->csize;
 
    /* Print the free space (assuming 512 bytes/sector) */
    printf("%10lu KiB total drive space.\n%10lu KiB available.\n", tot_sect / 2, fre_sect / 2);