# 文件系统

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

文件系统是指文件和对文件进行操作和管理的软件的集合。文件系统实现了存储空间管理、构造文件结构、提供访问文件的操作接口。使用文件系统存储方式可以方便进行文件的增、删、查、改。

本章主要介绍UniRTOS虚拟文件系统（VFS）的功能特性、API使用方法及典型应用示例，旨在帮助开发者快速掌握文件系统操作能力的集成与调试，确保设备在各种存储介质和平台下稳定可靠运行。

## VFS

VFS（Virtual File System，虚拟文件系统）是操作系统中承上启下的关键抽象层——它对上层应用提供统一的POSIX风格文件操作接口（open/read/write/close等），对下层屏蔽不同文件系统实现的差异。各存储分区（如 */user*、*/fota*、*/data*）在系统启动阶段已由平台完成挂载，应用代码只需使用标准路径即可操作文件，无需关心底层是何种存储介质。UniRTOS的VFS实现由 *qosa_vfs* 系列接口承载，是文件系统栈的核心枢纽。

### UniRTOS VFS的核心能力

UniRTOS VFS的核心能力包括：

- 统一文件操作：提供 *open/close/read/write/lseek/stat/truncate* 等标准POSIX语义接口，应用层使用系统路径（如 */user/config.json*）访问已挂载分区中的文件，降低有嵌入式Linux开发经验者的学习成本；

- 完整目录管理：支持目录的创建、删除、遍历、递归操作，以及工作目录切换和路径规范化；

- 文件系统信息查询：获取挂载点列表、文件系统容量、剩余空间、块大小等统计信息，为存储空间监控和预警提供数据基础；

- 运行时挂载管理：支持文件系统的运行时卸载和只读重新挂载，满足FOTA升级、安全模式切换等动态场景需求。

### 典型高频应用场景

典型高频应用场景包括：

- 配置文件管理：设备首次上电时通过 *qosa_vfs_open()* 检查配置文件是否存在，不存在则创建默认配置；运行期间通过 *qosa_vfs_read()* 和 *qosa_vfs_write()* 读写配置参数；

- 日志文件记录：通过 *qosa_vfs_open()* 创建日志文件，配合 *qosa_vfs_lseek()* 和 *qosa_vfs_ftruncate()* 实现按大小滚动覆写，避免日志文件无限增长耗尽存储空间；

- FOTA升级流程：通过 *qosa_vfs_statvfs()* 校验FOTA分区容量，使用辅助函数 *qosa_vfs_file_write()* 将固件包一次性写入，升级后卸载旧分区重新挂载新固件；

- 存储空间监控：定期调用 *qosa_vfs_statvfs()* 或 *qosa_vfs_dir_total_size()* 查询存储使用情况，低于阈值时触发清理策略或上报告警；

- 工厂文件保护：利用 *qosa_vfs_remount()* 将配置分区切换为只读模式，防止运行期间误写关键出厂参数。

# 文件系统API

## 头文件

*qosa_virtual_file.h*

## 函数概览

### 文件操作

| **函数** | **说明** |
| --- | --- |
| *qosa_vfs_creat()* | 创建文件 |
| *qosa_vfs_open()* | 打开文件（可创建） |
| *qosa_vfs_close()* | 关闭文件描述符 |
| *qosa_vfs_read()* | 读取文件数据 |
| *qosa_vfs_write()* | 写入文件数据 |
| *qosa_vfs_lseek()* | 设置文件读写偏移 |
| *qosa_vfs_fstat()* | 通过文件描述符获取文件状态 |
| *qosa_vfs_stat()* | 通过文件路径获取文件状态 |
| *qosa_vfs_truncate()* | 通过路径截断文件到指定长度 |
| *qosa_vfs_ftruncate()* | 通过文件描述符截断文件到指定长度 |
| *qosa_vfs_unlink()* | 删除文件 |
| *qosa_vfs_rename()* | 重命名或移动文件 |
| *qosa_vfs_fsync()* | 将文件数据同步到存储设备 |
| *qosa_vfs_file_size()* | 获取文件大小（辅助函数） |
| *qosa_vfs_file_read()* | 一次性读取文件（辅助函数） |
| *qosa_vfs_file_write()* | 一次性写入文件（辅助函数） |

### 目录操作

| **函数** | **说明** |
| --- | --- |
| *qosa_vfs_mkdir()* | 创建目录 |
| *qosa_vfs_rmdir()* | 删除空目录 |
| *qosa_vfs_opendir()* | 打开目录流 |
| *qosa_vfs_readdir()* | 读取目录条目 |
| *qosa_vfs_readdir_r()* | 读取目录条目（线程安全版本） |
| *qosa_vfs_closedir()* | 关闭目录流 |
| *qosa_vfs_telldir()* | 获取目录流当前位置 |
| *qosa_vfs_seekdir()* | 设置目录流读取位置 |
| *qosa_vfs_rewinddir()* | 重置目录流到起始位置 |
| *qosa_vfs_mkpath()* | 递归创建多级目录 |
| *qosa_vfs_mkfilepath()* | 递归创建文件所在目录 |
| *qosa_vfs_rmchildren()* | 删除目录下所有子文件和子目录 |
| *qosa_vfs_rmdir_recursive()* | 递归删除目录及其内容 |
| *qosa_vfs_chdir()* | 切换工作目录 |
| *qosa_vfs_getcwd()* | 获取当前工作目录 |

### 文件系统管理

| **函数** | **说明** |
| --- | --- |
| *qosa_vfs_statvfs()* | 通过路径获取文件系统统计信息 |
| *qosa_vfs_fstatvfs()* | 通过文件描述符获取文件系统统计信息 |
| *qosa_vfs_mount_count()* | 获取已挂载文件系统数量 |
| *qosa_vfs_mount_points()* | 获取已挂载文件系统挂载点列表 |
| *qosa_vfs_umount()* | 卸载文件系统 |
| *qosa_vfs_remount()* | 重新挂载文件系统 |
| *qosa_vfs_umount_all()* | 卸载所有已挂载文件系统 |
| *qosa_vfs_dir_total_size()* | 获取目录下文件总大小 |
| *qosa_vfs_realpath()* | 获取规范化绝对路径 |
| *qosa_vfs_sync()* | 将文件系统缓冲区数据刷入磁盘 |

## 函数详解

### qosa_vfs_creat

- **功能描述**  
  创建文件，等效于以 *QOSA_VFS_O_WRONLY | QOSA_VFS_O_CREAT | QOSA_VFS_O_TRUNC* 方式打开文件。

- **函数原型**

```c
qosa_int32_t qosa_vfs_creat(const char *path, qosa_int32_t mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径；必须为绝对路径 |
| *mode* | 输入 | qosa_int32_t | 文件权限模式 |

- **返回值说明**  
  非负值：函数执行成功，返回文件描述符  
  *-1*：函数执行失败

### qosa_vfs_open

- **功能描述**  
  打开文件，支持创建不存在的文件。

- **函数原型**

```c
qosa_int32_t qosa_vfs_open(const char *path, qosa_int32_t flags)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径；必须为绝对路径 |
| *flags* | 输入 | qosa_int32_t | 文件打开标志；支持 *QOSA_VFS_O_RDONLY*、*QOSA_VFS_O_WRONLY*、*QOSA_VFS_O_RDWR* 等，可与 *QOSA_VFS_O_CREAT*、*QOSA_VFS_O_TRUNC* 等标志按位或组合；详见 [文件打开标志](#文件打开标志) |

- **返回值说明**  
  非负值：函数执行成功，返回文件描述符  
  *-1*：函数执行失败

### qosa_vfs_close

- **功能描述**  
  关闭已打开的文件描述符，释放相关资源。

- **函数原型**

```c
qosa_int32_t qosa_vfs_close(qosa_int32_t fd)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 待关闭的文件描述符 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_read

- **功能描述**  
  从已打开的文件描述符中读取数据。

- **函数原型**

```c
qosa_ssize_t qosa_vfs_read(qosa_int32_t fd, void *buf, qosa_size_t count)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *buf* | 输出 | void * | 数据读取缓冲区 |
| *count* | 输入 | qosa_size_t | 期望读取的字节数 |

- **返回值说明**  
  非负值：函数执行成功，返回实际读取的字节数  
  *-1*：函数执行失败

### qosa_vfs_write

- **功能描述**  
  向已打开的文件描述符写入数据。

- **函数原型**

```c
qosa_ssize_t qosa_vfs_write(qosa_int32_t fd, const void *buf, qosa_size_t count)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *buf* | 输入 | const void * | 待写入数据缓冲区 |
| *count* | 输入 | qosa_size_t | 期望写入的字节数 |

- **返回值说明**  
  非负值：函数执行成功，返回实际写入的字节数  
  *-1*：函数执行失败

### qosa_vfs_lseek

- **功能描述**  
  重新定位文件读写偏移量。

- **函数原型**

```c
qosa_int64_t qosa_vfs_lseek(qosa_int32_t fd, qosa_int64_t offset, qosa_int32_t whence)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *offset* | 输入 | qosa_int64_t | 偏移量；相对于 *whence* 参数指定的位置 |
| *whence* | 输入 | qosa_int32_t | 偏移起始位置<br>*QOSA_VFS_SEEK_SET*：从文件起始位置偏移  <br>*QOSA_VFS_SEEK_CUR*：从当前位置偏移  <br>*QOSA_VFS_SEEK_END*：从文件末尾位置偏移；详见 [文件偏移标志](#文件偏移标志) |

- **返回值说明**  
  非负值：函数执行成功，返回从文件起始位置计算的新偏移量；单位：字节  
  *-1*：函数执行失败

### qosa_vfs_fstat

- **功能描述**  
  通过文件描述符获取文件状态信息。

- **函数原型**

```c
qosa_int32_t qosa_vfs_fstat(qosa_int32_t fd, struct qosa_vfs_stat_t *st)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *st* | 输出 | *struct qosa_vfs_stat_t ** | 指向文件状态结构体的指针；详见 [*qosa_vfs_stat_t*](#qosavfsstat_t) |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_stat

- **功能描述**  
  通过文件路径获取文件状态信息。

- **函数原型**

```c
qosa_int32_t qosa_vfs_stat(const char *path, struct qosa_vfs_stat_t *st)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径 |
| *st* | 输出 | *struct qosa_vfs_stat_t ** | 指向文件状态结构体的指针；详见 [*qosa_vfs_stat_t*](#qosavfsstat_t) |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_truncate

- **功能描述**  
  将指定路径的文件截断到指定长度。若文件长度小于指定长度，文件将被扩展；若大于指定长度，文件将被截断。

- **函数原型**

```c
qosa_int32_t qosa_vfs_truncate(const char *path, long length)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径 |
| *length* | 输入 | long | 文件截断后的目标长度；单位：字节 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_ftruncate

- **功能描述**  
  通过文件描述符将文件截断到指定长度。

- **函数原型**

```c
qosa_int32_t qosa_vfs_ftruncate(qosa_int32_t fd, long length)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *length* | 输入 | long | 文件截断后的目标长度；单位：字节 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_unlink

- **功能描述**  
  删除指定路径的文件。

- **函数原型**

```c
qosa_int32_t qosa_vfs_unlink(const char *pathname)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pathname* | 输入 | const char * | 待删除的文件路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_rename

- **功能描述**  
  重命名或移动文件。源路径和目标路径必须在同一个挂载的文件系统上。

- **函数原型**

```c
qosa_int32_t qosa_vfs_rename(const char *oldpath, const char *newpath)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *oldpath* | 输入 | const char * | 原文件路径 |
| *newpath* | 输入 | const char * | 新文件路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败  
  *EXDEV*：源路径和目标路径不在同一个挂载的文件系统上

### qosa_vfs_fsync

- **功能描述**  
  将文件的内存缓冲区数据同步写入存储设备，确保数据持久化。

- **函数原型**

```c
qosa_int32_t qosa_vfs_fsync(qosa_int32_t fd)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_file_size

- **功能描述**  
  获取指定路径文件的大小。内部调用 *qosa_vfs_stat()* 获取文件状态并返回文件大小。

- **函数原型**

```c
qosa_ssize_t qosa_vfs_file_size(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径 |

- **返回值说明**  
  非负值：函数执行成功，返回文件大小；单位：字节  
  *-1*：函数执行失败

### qosa_vfs_file_read

- **功能描述**  
  一次性读取整个文件的辅助函数。内部依次调用 *qosa_vfs_open()*、*qosa_vfs_read()* 和 *qosa_vfs_close()* 完成操作。

- **函数原型**

```c
qosa_ssize_t qosa_vfs_file_read(const char *path, void *buf, qosa_size_t count)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径 |
| *buf* | 输出 | void * | 数据读取缓冲区 |
| *count* | 输入 | qosa_size_t | 期望读取的字节数 |

- **返回值说明**  
  非负值：函数执行成功，返回实际读取的字节数  
  *-1*：函数执行失败

### qosa_vfs_file_write

- **功能描述**  
  一次性写入整个文件的辅助函数。内部依次调用 *qosa_vfs_open()*、*qosa_vfs_write()* 和 *qosa_vfs_close()* 完成操作。

- **函数原型**

```c
qosa_ssize_t qosa_vfs_file_write(const char *path, const void *buf, qosa_size_t count)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径 |
| *buf* | 输入 | const void * | 待写入数据缓冲区 |
| *count* | 输入 | qosa_size_t | 期望写入的字节数 |

- **返回值说明**  
  非负值：函数执行成功，返回实际写入的字节数  
  *-1*：函数执行失败

### qosa_vfs_mkdir

- **功能描述**  
  创建单级目录。

- **函数原型**

```c
qosa_int32_t qosa_vfs_mkdir(const char *pathname, qosa_int32_t mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pathname* | 输入 | const char * | 待创建目录路径 |
| *mode* | 输入 | qosa_int32_t | 目录权限模式；可能被文件系统实现忽略 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_rmdir

- **功能描述**  
  删除空目录。

- **函数原型**

```c
qosa_int32_t qosa_vfs_rmdir(const char *pathname)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pathname* | 输入 | const char * | 待删除的目录路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_opendir

- **功能描述**  
  打开目录流，返回目录句柄用于后续目录遍历操作。

- **函数原型**

```c
QOSA_VFS_DIR *qosa_vfs_opendir(const char *name)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *name* | 输入 | const char * | 待打开的目录路径 |

- **返回值说明**  
  非NULL：函数执行成功，返回指向目录流的指针  
  *NULL*：函数执行失败

### qosa_vfs_readdir

- **功能描述**  
  读取目录流中的下一个目录条目。

- **函数原型**

```c
struct qosa_vfs_dirent_t *qosa_vfs_readdir(QOSA_VFS_DIR *dirp)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *dirp* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |

- **返回值说明**  
  非NULL：函数执行成功，返回指向目录条目结构体的指针  
  *NULL*：已到达目录末尾或函数执行失败

### qosa_vfs_readdir_r

- **功能描述**  
  读取目录流中的下一个目录条目（线程安全版本）。

- **函数原型**

```c
qosa_int32_t qosa_vfs_readdir_r(QOSA_VFS_DIR *dirp, struct qosa_vfs_dirent_t *entry, struct qosa_vfs_dirent_t **result)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *dirp* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |
| *entry* | 输出 | *struct qosa_vfs_dirent_t ** | 用于存储读取结果的目录条目缓冲区；详见 [*qosa_vfs_dirent_t*](#qosavfsdirent_t) |
| *result* | 输出 | *struct qosa_vfs_dirent_t *** | 指向结果指针；成功时指向 *entry*，到达目录末尾时为 *NULL* |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_closedir

- **功能描述**  
  关闭已打开的目录流，释放相关资源。

- **函数原型**

```c
qosa_int32_t qosa_vfs_closedir(QOSA_VFS_DIR *pdir)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pdir* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_telldir

- **功能描述**  
  获取目录流的当前读取位置。

- **函数原型**

```c
long qosa_vfs_telldir(QOSA_VFS_DIR *pdir)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pdir* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |

- **返回值说明**  
  非负值：函数执行成功，返回当前目录流位置  
  *-1*：函数执行失败

### qosa_vfs_seekdir

- **功能描述**  
  设置目录流中下次 *qosa_vfs_readdir()* 调用的读取位置。

- **函数原型**

```c
void qosa_vfs_seekdir(QOSA_VFS_DIR *pdir, long loc)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pdir* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |
| *loc* | 输入 | long | 目标位置；由 *qosa_vfs_telldir()* 返回 |

- **返回值说明**  
  无

### qosa_vfs_rewinddir

- **功能描述**  
  将目录流的读取位置重置到起始位置。

- **函数原型**

```c
void qosa_vfs_rewinddir(QOSA_VFS_DIR *pdir)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *pdir* | 输入 | *QOSA_VFS_DIR ** | 由 *qosa_vfs_opendir()* 返回的目录流指针；详见 [*QOSA_VFS_DIR*](#qosavfsdir) |

- **返回值说明**  
  无

### qosa_vfs_mkpath

- **功能描述**  
  递归创建多级目录，自动创建路径中所有不存在的父级目录。

- **函数原型**

```c
qosa_int32_t qosa_vfs_mkpath(const char *path, qosa_int32_t mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 待创建的多级目录路径 |
| *mode* | 输入 | qosa_int32_t | 目录权限模式 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_mkfilepath

- **功能描述**  
  递归创建文件所在的所有父级目录。传入文件路径，自动创建该文件路径中不存在的目录层级。

- **函数原型**

```c
qosa_int32_t qosa_vfs_mkfilepath(const char *path, qosa_int32_t mode)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径（函数会创建该路径的父级目录） |
| *mode* | 输入 | qosa_int32_t | 目录权限模式 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_rmchildren

- **功能描述**  
  删除指定目录下的所有子文件和子目录，但保留该目录本身。

- **函数原型**

```c
qosa_int32_t qosa_vfs_rmchildren(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 目标目录路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_rmdir_recursive

- **功能描述**  
  递归删除指定目录及其下所有子文件和子目录。

- **函数原型**

```c
qosa_int32_t qosa_vfs_rmdir_recursive(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 待递归删除的目录路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_chdir

- **功能描述**  
  切换当前工作目录。在RTOS系统中工作目录是全局概念，切换工作目录可能影响其他任务，请谨慎使用。

- **函数原型**

```c
qosa_int32_t qosa_vfs_chdir(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 目标目录路径 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_getcwd

- **功能描述**  
  获取当前工作目录的绝对路径。

- **函数原型**

```c
char *qosa_vfs_getcwd(char *buf, qosa_size_t size)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *buf* | 输出 | char * | 用于存储当前工作目录的缓冲区 |
| *size* | 输入 | qosa_size_t | 缓冲区大小；单位：字节 |

- **返回值说明**  
  非NULL：函数执行成功，返回当前工作目录路径字符串指针  
  *NULL*：函数执行失败

### qosa_vfs_statvfs

- **功能描述**  
  通过文件路径获取文件系统的统计信息，包括总容量、可用空间、块大小等。

- **函数原型**

```c
qosa_int32_t qosa_vfs_statvfs(const char *path, struct qosa_vfs_statvfs_t *buf)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件系统中的任意路径 |
| *buf* | 输出 | *struct qosa_vfs_statvfs_t ** | 指向文件系统统计信息结构体的指针；详见 [*qosa_vfs_statvfs_t*](#qosavfsstatvfs_t) |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_fstatvfs

- **功能描述**  
  通过已打开的文件描述符获取文件系统的统计信息。

- **函数原型**

```c
qosa_int32_t qosa_vfs_fstatvfs(qosa_int32_t fd, struct qosa_vfs_statvfs_t *buf)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 文件描述符 |
| *buf* | 输出 | *struct qosa_vfs_statvfs_t ** | 指向文件系统统计信息结构体的指针；详见 [*qosa_vfs_statvfs_t*](#qosavfsstatvfs_t) |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

### qosa_vfs_mount_count

- **功能描述**  
  获取当前系统中已挂载的文件系统数量。

- **函数原型**

```c
qosa_int32_t qosa_vfs_mount_count(void)
```

- **参数说明**  
  无

- **返回值说明**  
  返回已挂载的文件系统数量

### qosa_vfs_mount_points

- **功能描述**  
  获取当前系统中所有已挂载文件系统的挂载点路径列表。

- **函数原型**

```c
qosa_int32_t qosa_vfs_mount_points(char **mp, qosa_size_t count)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *mp* | 输出 | char ** | 用于存储挂载点路径的字符串数组 |
| *count* | 输入 | qosa_size_t | 数组元素数量 |

- **返回值说明**  
  返回实际获取的挂载点数量

### qosa_vfs_umount

- **功能描述**  
  卸载指定路径所在的文件系统。路径必须为绝对路径，可以是挂载点本身，也可以是挂载点下的任意文件或目录。

- **函数原型**

```c
qosa_int32_t qosa_vfs_umount(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 文件路径；必须为绝对路径（以'/'开头） |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败（参数无效或没有对应的挂载点）

### qosa_vfs_remount

- **功能描述**  
  以指定标志重新挂载文件系统。仅支持 *QOSA_MS_RDONLY* 只读挂载标志。路径必须为挂载点。

- **函数原型**

```c
qosa_int32_t qosa_vfs_remount(const char *path, unsigned flags)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 挂载点路径 |
| *flags* | 输入 | unsigned | 挂载标志  <br>*QOSA_MS_RDONLY*：以只读模式重新挂载 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败（路径不是挂载点或文件系统不支持重新挂载）

### qosa_vfs_umount_all

- **功能描述**  
  卸载所有已挂载的文件系统。仅在FDL模式下有效，应用层实现为空函数。

- **函数原型**

```c
void qosa_vfs_umount_all(void)
```

- **参数说明**  
  无

- **返回值说明**  
  无

### qosa_vfs_dir_total_size

- **功能描述**  
  递归计算指定目录下所有文件的总大小。

- **函数原型**

```c
qosa_int64_t qosa_vfs_dir_total_size(const char *path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 目录路径 |

- **返回值说明**  
  非负值：函数执行成功，返回目录下所有文件的总大小；单位：字节  
  *-1*：函数执行失败（参数无效或内存不足）

### qosa_vfs_realpath

- **功能描述**  
  将文件路径转换为规范化的绝对路径，消除路径中的"."和".."等相对引用。

- **函数原型**

```c
char *qosa_vfs_realpath(const char *path, char *resolved_path)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *path* | 输入 | const char * | 待解析的文件路径 |
| *resolved_path* | 输出 | char * | 用于存储规范化绝对路径的缓冲区 |

- **返回值说明**  
  非NULL：函数执行成功，返回 *resolved_path* 指针  
  *NULL*：函数执行失败

### qosa_vfs_sync

- **功能描述**  
  将文件系统缓冲区中的数据强制刷入磁盘。

- **函数原型**

```c
qosa_int32_t qosa_vfs_sync(qosa_int32_t fd)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *fd* | 输入 | qosa_int32_t | 待同步的文件描述符 |

- **返回值说明**  
  *0*：函数执行成功  
  *-1*：函数执行失败

## 结构体定义

### qosa_vfs_stat_t

文件状态信息结构体定义如下：

```c
struct qosa_vfs_stat_t
{
    qosa_uint64_t st_dev;     
    qosa_uint64_t st_ino;    
    qosa_uint64_t st_mode;    
    qosa_uint64_t st_nlink;   
    qosa_uint64_t st_uid;     
    qosa_uint64_t st_gid;     
    qosa_uint64_t st_rdev;   
    qosa_uint64_t st_size;   
    qosa_uint64_t st_spare1;
    qosa_uint64_t st_spare2;
    qosa_uint64_t st_spare3;
    qosa_uint64_t st_blksize; 
    qosa_uint64_t st_blocks;   
    qosa_uint64_t st_spare4[2];
};
```

| **成员** | **说明** |
| --- | --- |
| *st_dev* | 设备ID |
| *st_ino* | i-node编号 |
| *st_mode* | 文件类型和权限 |
| *st_nlink* | 硬链接数量 |
| *st_uid* | 所有者用户ID |
| *st_gid* | 所有者组ID |
| *st_rdev* | 设备ID（若文件为设备文件） |
| *st_size* | 文件大小；单位：字节 |
| *st_spare1* | 保留字段 |
| *st_spare2* | 保留字段 |
| *st_spare3* | 保留字段 |
| *st_blksize* | I/O操作块大小 |
| *st_blocks* | 文件占用的块数 |
| *st_spare4* | 保留字段 |

### QOSA_VFS_DIR

目录操作句柄结构体定义如下：

```c
typedef struct
{
    qosa_int16_t fs_index;  
    qosa_int16_t _reserved; 
} QOSA_VFS_DIR;
```

| **成员** | **说明** |
| --- | --- |
| *fs_index* | 内部文件系统索引标识 |
| *_reserved* | 保留字段，用于字节对齐或未来扩展 |

### qosa_vfs_dirent_t

目录条目信息结构体定义如下：

```c
struct qosa_vfs_dirent_t
{
    qosa_int32_t  d_ino;       
    unsigned char d_type;      
    char          d_name[256]; 
};
```

| **成员** | **说明** |
| --- | --- |
| *d_ino* | inode编号；文件系统实现可自定义用途 |
| *d_type* | 文件类型标识  <br>*QOSA_VFS_DT_REG*：普通文件  <br>*QOSA_VFS_DT_DIR*：目录；详见 [文件类型标识](#文件类型标识) |
| *d_name* | 文件名（不含路径部分）；最大256字节 |

### qosa_vfs_statvfs_t

文件系统统计信息结构体定义如下：

```c
struct qosa_vfs_statvfs_t
{
    unsigned long f_bsize;   
    unsigned long f_frsize;  
    unsigned long f_blocks;  
    unsigned long f_bfree;  
    unsigned long f_bavail; 
    unsigned long f_files;  
    unsigned long f_ffree;  
    unsigned long f_favail;  
    unsigned long f_fsid;     
    unsigned long f_flag;     
    unsigned long f_namemax; 
};
```

| **成员** | **说明** |
| --- | --- |
| *f_bsize* | 文件系统块大小；单位：字节 |
| *f_frsize* | 分片大小；单位：字节 |
| *f_blocks* | 文件系统总块数（以 *f_frsize* 为单位） |
| *f_bfree* | 文件系统空闲块数 |
| *f_bavail* | 非超级用户可用的空闲块数 |
| *f_files* | 文件系统中的文件节点总数 |
| *f_ffree* | 文件系统中的空闲文件节点数 |
| *f_favail* | 可用的文件节点数 |
| *f_fsid* | 文件系统ID标识符 |
| *f_flag* | 挂载标志 |
| *f_namemax* | 文件名最大长度 |

## 宏定义

### 文件打开标志

```c
#define QOSA_VFS_O_RDONLY    
#define QOSA_VFS_O_WRONLY     
#define QOSA_VFS_O_RDWR      
#define QOSA_VFS_O_CREAT    
#define QOSA_VFS_O_EXCL      
#define QOSA_VFS_O_TRUNC     
#define QOSA_VFS_O_APPEND     
```

| **宏名** | **说明** |
| --- | --- |
| *QOSA_VFS_O_RDONLY* | 只读模式打开文件 |
| *QOSA_VFS_O_WRONLY* | 只写模式打开文件 |
| *QOSA_VFS_O_RDWR* | 读写模式打开文件，与 *QOSA_VFS_O_RDONLY* 和 *QOSA_VFS_O_WRONLY* 互斥 |
| *QOSA_VFS_O_CREAT* | 文件不存在时自动创建 |
| *QOSA_VFS_O_EXCL* | 配合 *QOSA_VFS_O_CREAT* 使用，文件已存在时打开失败 |
| *QOSA_VFS_O_TRUNC* | 文件存在且以可写模式打开时，清空文件内容，长度置0 |
| *QOSA_VFS_O_APPEND* | 写入数据时从文件末尾追加 |

### 文件偏移标志

```c
#define QOSA_VFS_SEEK_SET    
#define QOSA_VFS_SEEK_CUR    
#define QOSA_VFS_SEEK_END     
```

| **宏名** | **说明** |
| --- | --- |
| *QOSA_VFS_SEEK_SET* | 从文件起始位置偏移 |
| *QOSA_VFS_SEEK_CUR* | 从当前读写位置偏移 |
| *QOSA_VFS_SEEK_END* | 从文件末尾位置偏移 |

### 文件类型标识

```c
#define QOSA_VFS_DT_DIR      4  
#define QOSA_VFS_DT_REG      8  
```

| **宏名** | **值** | **说明** |
| --- | --- | --- |
| *QOSA_VFS_DT_DIR* | 4 | 目录 |
| *QOSA_VFS_DT_REG* | 8 | 普通文件 |

### 路径长度限制

```c
#define QOSA_VFS_PATH_MAX    192 
```

| **宏名** | **值** | **说明** |
| --- | --- | --- |
| *QOSA_VFS_PATH_MAX* | 192 | 最大绝对文件路径长度（含挂载点和终止符\0） |

# 应用逻辑流程图

## 文件操作流程

```{figure} images/board_FQgkwU87YhksfxbQarVcEctkncc.jpg
:align: center
:alt: image
```

## 目录操作流程

```{figure} images/board_E5C5ww83FhejhqbO3Kyczv1mn6e.jpg
:align: center
:alt: image
```

# 示例代码

完整示例代码请查看 [https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/vfs/vfs.c](<https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/vfs/vfs.c> )