insert component/fs.md

docs/doc/component/fs.md

@@ -1 +1,270 @@
 # 文件系统
+
+## 简介
+当前，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的应用程序架构如下图所示。
+
+<center>
+
+![fs](./imagesrc/fs.png)
+
+</center>
+
+## 文件系统接口
+
+```c
+int xs_MountFilesystem(const char *device_name,
+        enum xs_FilesystemType fs_type, const char *path);
+```
+
+该函数用于将指定设备上的物理文件系统挂载到指定路径。若挂载成功则返回0；若失败则返回对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| device_name | 待挂载的设备名 |
+| fs_type | 设备上的物理文件系统类型，目前只支持FSTYPE_FATFS |
+| path | 挂载路径 |
+
+```c
+int xs_UnmountFileSystem(const char *path);
+```
+
+该函数用于卸载指定路径上挂载的文件系统。若卸载成功则返回0；若失败则返回对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待卸载的路径 |
+
+## POSIX文件接口
+
+```c
+int open(const char *path, int flags, ...);
+```
+
+该函数用于打开一个文件。若文件打开成功则返回该文件的描述符（非负），后续读写该文件由该描述符标识；若不成功则返回-1，此时errno会被置为对应错误码。在打开文件时可以指定打开选项，即flags参数。可选的选项有打开时截断文件（O_TRUNC）和向末尾写入（O_APPEND）。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 打开文件的路径 |
+| flags | 打开选项 |
+
+```c
+int close(int fd);
+```
+
+该函数用于关闭一个已打开的文件。若文件关闭成功则返回0；若不成功则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待关闭文件描述符 |
+
+```c
+int read(int fd, void *buf, size_t len);
+```
+
+该函数用于从文件读取数据。若读取成功则返回读取到的字节数；若不成功则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待读取文件描述符 |
+| buf | 存放读取数据的缓冲区首地址 |
+| len | 缓冲区长度，单位为字节 |
+
+```c
+int write(int fd, const void *buf, size_t len);
+```
+
+该函数用于向文件写入数据。若写入成功则返回读取到的字节数；若不成功则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待写入文件描述符 |
+| buf | 存放写入数据的缓冲区首地址 |
+| len | 缓冲区长度，单位为字节 |
+
+```c
+off_t lseek(int fd, off_t offset, int whence);
+```
+
+该函数用于重定位文件读写指针。若重定位成功则返回新的读写指针位置，即距离文件起始处的字节数；若不成功则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待重定位的文件描述符 |
+| offset | 新的文件读写指针位置 |
+| whence | offset参数的参照位置，可以为文件起始（SEEK_SET）、当前位置（SEEK_CUR）、文件末尾（SEEK_END） |
+
+```c
+int rename(const char *from, const char *to);
+```
+
+该函数用于重命名文件。若重命名成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| from | 原文件路径 |
+| to | 新文件路径，若与原路径属于不同目录则文件会被移动 |
+
+```c
+int unlink(const char *path);
+```
+
+该函数用于删除一个文件。若删除成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待删除文件路径 |
+
+```c
+int stat(const char *path, struct stat *buf);
+```
+
+该函数用于获取文件的元数据。stat结构与POSIX定义相同。若获取成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待获取元数据的文件路径 |
+| buf | 一个stat结构实例指针，用于存储元数据 |
+
+```c
+int fstat(int fd, struct stat *buf);
+```
+
+该函数用于获取文件的元数据。stat结构与POSIX定义相同。若获取成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待获取元数据的文件描述符 |
+| buf | 一个stat结构实例指针，用于存储元数据 |
+
+```c
+int fsync(int fd);
+```
+
+该函数用于将指定文件数据写回存储设备，从而防止系统掉电数据丢失。若写回成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待写回文件描述符 |
+
+```c
+int ftruncate(int fd, off_t length);
+```
+
+该函数用于将文件截断至指定长度。若截断成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| fd | 待截断文件描述符 |
+| length | 截断后的长度 |
+
+```c
+int mkdir(const char *path, mode_t mode);
+```
+
+该函数用于创建一个目录。若创建成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待创建目录的路径 |
+| mode | 目前该参数无用 |
+
+```c
+DIR *opendir(const char *path);
+```
+
+该函数用于打开一个目录。若打开成功则返回一个目录句柄；若失败则返回XS_NULL。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待打开目录的路径 |
+
+```c
+int closedir(DIR *dirp);
+```
+
+该函数用于关闭一个已打开的目录。若关闭成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| dirp | 待关闭目录句柄 |
+
+```c
+struct dirent *readdir(DIR *dirp);
+```
+
+该函数用于读取目录的目录项。目录项由dirent结构表示，目前该结构仅包含文件或目录的类型（d_kind）与名称（d_name）。若读取成功则返回一个dirent指针；若读取失败则返回XS_NULL，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| dirp | 待读取目录句柄 |
+
+```c
+int rmdir(const char *path);
+```
+
+该函数用于删除一个目录。若删除成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 待删除目录的路径 |
+
+```c
+int chdir(const char *path);
+```
+
+该函数用于切换当前工作目录。若切换成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| path | 新的工作目录路径 |
+
+```c
+char *getcwd(char *buf, size_t size);
+```
+
+该函数用于获取当前的工作目录。若获取成功则返回工作目录字符串（与buf参数相同）；若失败则返回XS_NULL，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| buf | 用于存储工作目录字符串的缓冲区首地址 |
+| size | 缓冲区大小 |
+
+```c
+void rewinddir(DIR *dirp);
+```
+
+该函数用于重置目录的读取位置，即下一次readdir将返回目录的第一个目录项。
+
+| 参数 | 描述 |
+| --- | --- |
+| dirp | 待重置读取位置的目录句柄 |
+
+```c
+long telldir(DIR *dirp);
+```
+
+该函数用于获取目录的读取位置，即下一个readdir返回目录项的位置。若获取成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| dirp | 待获取读取位置的目录句柄 |
+
+```c
+void seekdir(DIR *dirp, off_t offset);
+```
+
+该函数用于设置目录的读取位置，即下一个readdir返回目录项的位置。若设置成功则返回0；若失败则返回-1，此时errno会被置为对应错误码。
+
+| 参数 | 描述 |
+| --- | --- |
+| dirp | 待设置读取位置的目录句柄 |
+| offset | 新的读取位置，应为某次telldir的返回值 |