# 文件系统
# 简介
当前，Linux和其他RTOS支持Ext2，Ext3，Ext4，XFS，BtrFS，F2FS，RAMFS等多种文件系统，因存储设备的硬件特征及其不同的应用场合，用户可以选择不同的文件系统。虚拟文件系统VFS的引入，使得这些不同的文件系统可以向外提供统一的编程接口和操作界面。
在物联网领域，主要使用的存储设备为FLASH，所以可以选择Jffs2等适合FLASH特性的日志型文件系统；FATFS由于其同时兼容Linux和Windows，选择其作为文件系统便于在“端”、“边”、“云”之间以统一的格式交互和保存数据。Ext4作为业内用户使用较多的文件系统，也可以将其轻量级的版本应用于物联网领域。
XiUOS研发计划支持FATFS，Jffs2，LWext4三种文件系统，目前XiUOS 1.0版本只支持FATFS。为了增强兼容性和支持VFS的特性，XiUOS通过设计IoT-VFS的构件，为用户提供了树形的文件组织结构。当前版本的IoT-VFS在功能上保证了FATFS的VFS特性，同时允许用户使用统一的VFS的接口来操作设备。IoT-VFS具有以下特性：
- 统一采用UNIX风格路径格式，目录与文件层级清晰分明
- 面向用户提供POSIX文件接口，降低应用程序移植难度
- 可以在任意路径挂载不同文件系统，并且可以便捷地添加对新的文件系统的支持
在IoT-VFS的支持下，应用程序开发者无须了解底层文件系统的接口细节，只需使用标准POSIX文件接口进行应用开发。对于已有的POSIX应用程序，也可以直接进行源代码级别的移植。使用IoT-VFS的应用程序架构如下图所示。
# 文件系统接口
int xs_MountFilesystem(const char *device_name,
enum xs_FilesystemType fs_type, const char *path);
该函数用于将指定设备上的物理文件系统挂载到指定路径，若挂载成功返回0，失败返回对应错误码。
| 参数 | 描述 |
|---|---|
| device_name | 待挂载的设备名 |
| fs_type | 设备上的物理文件系统类型，目前只支持FSTYPE_FATFS |
| path | 挂载路径 |
int xs_UnmountFileSystem(const char *path);
该函数用于卸载指定路径上挂载的文件系统，若卸载成功返回0，失败返回对应错误码。
| 参数 | 描述 |
|---|---|
| path | 待卸载的路径 |
# POSIX文件接口
int open(const char *path, int flags, ...);
该函数用于打开一个文件。若文件打开成功则返回该文件的描述符（非负），后续读写该文件由该描述符标识，若不成功则返回-1，此时errno会被置为对应错误码。在打开文件时可以指定打开选项，即flags参数。可选的选项有打开时截断文件（O_TRUNC）和向末尾写入（O_APPEND）。
| 参数 | 描述 |
|---|---|
| path | 打开文件的路径 |
| flags | 打开选项 |
int close(int fd);
该函数用于关闭一个已打开的文件。若文件关闭成功则返回0，若不成功则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待关闭文件描述符 |
int read(int fd, void *buf, size_t len);
该函数用于从文件读取数据。若读取成功则返回读取到的字节数，若不成功则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待读取文件描述符 |
| buf | 存放读取数据的缓冲区首地址 |
| len | 缓冲区长度，单位为字节 |
int write(int fd, const void *buf, size_t len);
该函数用于向文件写入数据。若写入成功则返回读取到的字节数，若不成功则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待写入文件描述符 |
| buf | 存放写入数据的缓冲区首地址 |
| len | 缓冲区长度，单位为字节 |
off_t lseek(int fd, off_t offset, int whence);
该函数用于重定位文件读写指针。若重定位成功则返回新的读写指针位置，即距离文件起始处的字节数，若不成功则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待重定位的文件描述符 |
| offset | 新的文件读写指针位置 |
| whence | offset参数的参照位置，可以为文件起始（SEEK_SET）、当前位置（SEEK_CUR）、文件末尾（SEEK_END） |
int rename(const char *from, const char *to);
该函数用于重命名文件。若重命名成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| from | 原文件路径 |
| to | 新文件路径，若与原路径属于不同目录则文件会被移动 |
int unlink(const char *path);
该函数用于删除一个文件。若删除成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| path | 待删除文件路径 |
int stat(const char *path, struct stat *buf);
该函数用于获取文件的元数据。stat结构与POSIX定义相同。若获取成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| path | 待获取元数据的文件路径 |
| buf | 一个stat结构实例指针，用于存储元数据 |
int fstat(int fd, struct stat *buf);
该函数用于获取文件的元数据。stat结构与POSIX定义相同。若获取成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待获取元数据的文件描述符 |
| buf | 一个stat结构实例指针，用于存储元数据 |
int fsync(int fd);
该函数用于将指定文件数据写回存储设备，从而防止系统掉电数据丢失。若写回成功则返回0，失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待写回文件描述符 |
int ftruncate(int fd, off_t length);
该函数用于将文件截断至指定长度。若截断成功则返回0，失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| fd | 待截断文件描述符 |
| length | 截断后的长度 |
int mkdir(const char *path, mode_t mode);
该函数用于创建一个目录。若创建成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| path | 待创建目录的路径 |
| mode | 目前该参数无用 |
DIR *opendir(const char *path);
该函数用于打开一个目录。若打开成功则返回一个目录句柄，若失败则返回XS_NULL。
| 参数 | 描述 |
|---|---|
| path | 待打开目录的路径 |
int closedir(DIR *dirp);
该函数用于关闭一个已打开的目录。若关闭成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| dirp | 待关闭目录句柄 |
struct dirent *readdir(DIR *dirp);
该函数用于读取目录的目录项。目录项由dirent结构表示，目前该结构仅包含文件或目录的类型（d_kind）与名称（d_name）。若读取成功则返回一个dirent指针，若读取失败则返回XS_NULL，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| dirp | 待读取目录句柄 |
int rmdir(const char *path);
该函数用于删除一个目录。若删除成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| path | 待删除目录的路径 |
int chdir(const char *path);
该函数用于切换当前工作目录。若切换成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| path | 新的工作目录路径 |
char *getcwd(char *buf, size_t size);
该函数用于获取当前的工作目录。若获取成功则返回工作目录字符串（与buf参数相同），若失败则返回 XS_NULL，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| buf | 用于存储工作目录字符串的缓冲区首地址 |
| size | 缓冲区大小 |
void rewinddir(DIR *dirp);
该函数用于重置目录的读取位置，即下一次readdir将返回目录的第一个目录项。
| 参数 | 描述 |
|---|---|
| dirp | 待重置读取位置的目录句柄 |
long telldir(DIR *dirp);
该函数用于获取目录的读取位置，即下一个readdir返回目录项的位置。若获取成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| dirp | 待获取读取位置的目录句柄 |
void seekdir(DIR *dirp, off_t offset);
该函数用于设置目录的读取位置，即下一个readdir返回目录项的位置。若设置成功则返回0，若失败则返回-1，此时errno会被置为对应错误码。
| 参数 | 描述 |
|---|---|
| dirp | 待设置读取位置的目录句柄 |
| offset | 新的读取位置，应为某次telldir的返回值 |