1# FAT<a name="EN-US_TOPIC_0000001153180399"></a> 2 3- [Basic Concepts](#section1772629121418) 4- [Development Guidelines](#section1149072811148) 5 - [Adaptation of Drivers](#section19174939191414) 6 - [How to Develop](#section131211626151513) 7 8- [Development Example](#section1133718619459) 9 - [Example Description](#section45337345313) 10 - [Sample Code](#section119813171539) 11 - [Verification](#section7987101232311) 12 13 14## Basic Concepts<a name="section1772629121418"></a> 15 16File Allocation Table \(FAT\) is a file system developed for personal computers. It consists of the DOS Boot Record \(DBR\) region, FAT region, and Data region. Each entry in the FAT region records information about the corresponding cluster in the storage device. The cluster information includes whether the cluster is used, number of the next cluster of the file, whether the file ends with the cluster. The FAT file system supports multiple formats, such as FAT12, FAT16, and FAT32. The numbers 12, 16, and 32 indicate the number of bytes per cluster within the FAT, respectively. The FAT file system supports multiple media, especially removable storage media \(such as USB flash drives, SD cards, and removable hard drives\). The FAT file system ensures good compatibility between embedded devices and desktop systems \(such as Windows and Linux\) and facilitates file management. 17 18The OpenHarmony kernel supports FAT12, FAT16, and FAT32 file systems. These file systems require a tiny amount of code to implement, use less resources, support a variety of physical media, and are tailorable and compatible with Windows and Linux systems. They also support identification of multiple devices and partitions. The kernel supports multiple partitions on hard drives and allows creation of the FAT file system on the primary partition and logical partition. 19 20## Development Guidelines<a name="section1149072811148"></a> 21 22### Adaptation of Drivers<a name="section19174939191414"></a> 23 24The use of the FAT file system requires support from the underlying MultiMediaCard \(MMC\) drivers. To run FatFS on a board with an MMC storage device, you must: 25 261. Implement the **disk\_status**, **disk\_initialize**, **disk\_read**, **disk\_write**, and **disk\_ioctl** APIs to adapt to the embedded MMC \(eMMC\) drivers on the board. 27 282. Add the **fs\_config.h** file with information such as **FS\_MAX\_SS** \(maximum sector size of the storage device\) and **FF\_VOLUME\_STRS** \(partition names\) configured. The following is an example: 29 30``` 31#define FF_VOLUME_STRS "system", "inner", "update", "user" 32#define FS_MAX_SS 512 33#define FAT_MAX_OPEN_FILES 50 34``` 35 36### How to Develop<a name="section131211626151513"></a> 37 38> **NOTE:** 39>- Note the following when managing FatFS files and directories: 40> - A file cannot exceed 4 GB. 41> - **FAT\_MAX\_OPEN\_FILES** specifies the maximum number files you can open at a time, and **FAT\_MAX\_OPEN\_DIRS** specifies the maximum number of folders you can open at a time. 42> - Root directory management is not supported. File and directory names start with the partition name. For example, **user/testfile** indicates the file or directory **testfile** in the **user** partition. 43> - To open a file multiple times, use **O\_RDONLY** \(read-only mode\). **O\_RDWR** or **O\_WRONLY** \(writable mode\) can open a file only once. 44> - The read and write pointers are not separated. If a file is open in **O\_APPEND** mode, the read pointer is also at the end of the file. If you want to read the file from the beginning, you must manually set the position of the read pointer. 45> - File and directory permission management is not supported. 46> - The **stat** and **fstat** APIs do not support query of the modification time, creation time, and last access time. The Microsoft FAT protocol does not support time before A.D. 1980. 47>- Note the following when mounting and unmounting FatFS partitions: 48> - Partitions can be mounted with the read-only attribute. When the input parameter of the **mount** function is **MS\_RDONLY**, all APIs with the write attribute, such as **write**, **mkdir**, **unlink**, and **open** with **non-O\_RDONLY** attributes, will be rejected. 49> - You can use the **MS\_REMOUNT** flag with **mount** to modify the permission for a mounted partition. 50> - Before unmounting a partition, ensure that all directories and files in the partition are closed. 51> - You can use **umount2** with the **MNT\_FORCE** parameter to forcibly close all files and folders and unmount the partition. However, this may cause data loss. Therefore, exercise caution when running **umount2**. 52>- The FAT file system supports re-partitioning and formatting of storage devices using **fatfs\_fdisk** and **fatfs\_format**. 53> - If a partition is mounted before being formatted using **fatfs\_format**, you must close all directories and files in the partition and unmount the partition first. 54> - Before calling **fatfs\_fdisk**, ensure that all partitions in the device are unmounted. 55> - Using **fatfs\_fdisk** and **fatfs\_format** may cause data loss. Exercise caution when using them. 56 57## Development Example<a name="section1133718619459"></a> 58 59### Example Description<a name="section45337345313"></a> 60 61This example implements the following: 62 631. Create the **user/test** directory. 642. Create the **file.txt** file in the **user/test** directory. 653. Write "Hello OpenHarmony!" at the beginning of the file. 664. Save the update of the file to the device. 675. Set the offset to the beginning of the file. 686. Read the file. 697. Close the file. 708. Delete the file. 719. Delete the directory. 72 73### Sample Code<a name="section119813171539"></a> 74 75Prerequisites 76 77- The MMC device partition is mounted to the **user** directory. 78 79The sample code is as follows: 80 81``` 82#include <stdio.h> 83#include <string.h> 84#include "sys/stat.h" 85#include "fcntl.h" 86#include "unistd.h" 87 88#define LOS_OK 0 89#define LOS_NOK -1 90 91int FatfsTest(void) 92{ 93 int ret; 94 int fd = -1; 95 ssize_t len; 96 off_t off; 97 char dirName[20] = "user/test"; 98 char fileName[20] = "user/test/file.txt"; 99 char writeBuf[20] = "Hello OpenHarmony!"; 100 char readBuf[20] = {0}; 101 102 /* Create the user/test directory.*/ 103 ret = mkdir(dirName, 0777); 104 if (ret != LOS_OK) { 105 printf("mkdir failed.\n"); 106 return LOS_NOK; 107 } 108 109 /* Create the file user/test/file.txt and make it readable and writable.*/ 110 fd = open(fileName, O_RDWR | O_CREAT, 0777); 111 if (fd < 0) { 112 printf("open file failed.\n"); 113 return LOS_NOK; 114 } 115 116 /* Write the content from writeBuf to the file. */ 117 len = write(fd, writeBuf, strlen(writeBuf)); 118 if (len != strlen(writeBuf)) { 119 printf("write file failed.\n"); 120 return LOS_NOK; 121 } 122 123 /* Save the update of the file to the device.*/ 124 ret = fsync(fd); 125 if (ret != LOS_OK) { 126 printf("fsync failed.\n"); 127 return LOS_NOK; 128 } 129 130 /* Move the read/write pointer to the file header. */ 131 off = lseek(fd, 0, SEEK_SET); 132 if (off != 0) { 133 printf("lseek failed.\n"); 134 return LOS_NOK; 135 } 136 137 /* Read the file content, with the same size as readBuf, to readBuf.*/ 138 len = read(fd, readBuf, sizeof(readBuf)); 139 if (len != strlen(writeBuf)) { 140 printf("read file failed.\n"); 141 return LOS_NOK; 142 } 143 printf("%s\n", readBuf); 144 145 /* Close the file. */ 146 ret = close(fd); 147 if (ret != LOS_OK) { 148 printf("close failed.\n"); 149 return LOS_NOK; 150 } 151 152 /*Delete the file user/test/file.txt.*/ 153 ret = unlink(fileName); 154 if (ret != LOS_OK) { 155 printf("unlink failed.\n"); 156 return LOS_NOK; 157 } 158 159 /*Delete the user/test directory.*/ 160 ret = rmdir(dirName); 161 if (ret != LOS_OK) { 162 printf("rmdir failed.\n"); 163 return LOS_NOK; 164 } 165 166 return LOS_OK; 167} 168``` 169 170### Verification<a name="section7987101232311"></a> 171 172The development is successful if the return result is as follows: 173 174``` 175Hello OpenHarmony! 176``` 177 178
