# 文件系统常见问题

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

---

# 为什么文件打不开？

## 路径格式用错了

*qosa_vfs* 和 *qcm_file* 的路径风格不同：

- *qosa_vfs* 建议使用真实绝对路径，例如 */user/test.txt*、*/data/log/app.log*。

- *qcm_file* 优先使用逻辑前缀路径，通常以UFS:、DATA:、FOTA:、SD:、EXTNOR: 开头。

## 父目录不存在

文件创建前如果父目录不存在，open或write很可能失败。

例如：

- */user/logs/app/app.log*

如果 */user/logs/app/* 没有先创建，直接创建文件可能失败。

建议先调用目录创建接口：

- *qosa_vfs_mkdir*

- *qcm_file_mkdir* 类接口

# 为什么创建文件或写文件失败？

## 存储空间不足

当前仓库保留了文件系统预留空间配置：

- *CONFIG_QOSA_FILE_CONFIG_RESERVE_SIZE*

它主要用于NV存储预留。即使看起来还有剩余空间，也可能因为预留区策略导致业务写入失败或可用空间比预期小。

建议：

- 使用 *qosa_vfs_statvfs* 或 *qcm_file* 的磁盘信息接口确认可用空间

- 对大文件写入前先做容量检查

- 不要把文件系统剩余空间全部吃满

## 文件系统只读

VFS支持只读重挂载标志：

- *QOSA_MS_RDONLY*

如果文件系统当前处于只读状态，创建、删除、重命名、写入都会失败，常见表现包括：

- 返回只读相关错误

- *qcm_file* 返回 *QCM_FILE_IS_READONLY* 或 *QCM_FILE_DEVICE_READONLY*

- 底层errno可能是EROFS

## 文件名或路径太长

当前仓库存在两类长度限制：

- VFS绝对路径最大长度：*QOSA_VFS_PATH_MAX* = *192*

- *qcm_file* 路径长度由文件名长度、目录长度和前缀长度共同决定

一旦超长，可能出现：

- open失败

- stat失败

- 返回exceeded max length或invalid file name一类错误

建议：

- 控制目录层级

- 日志文件名不要叠加过长时间戳和业务标识

## 打开的文件太多

*qcm_file* 显示定义了“达到最大打开文件数量”的错误码：

- *QCM_FILE_REACH_MAX_OPENFILE_NUM*

部分平台还定义了底层“打开文件过多”的平台错误。

建议：

- 每次打开后及时关闭

- 出错路径也要关闭fd或文件句柄

- 长时间运行任务避免句柄泄漏

# 为什么读文件返回0或读不到完整内容？

## 已经读到文件末尾

如果之前已经读取过，当前文件偏移可能已经在EOF位置。再次读取返回0是正常表现。

处理方法：

- 调用 *qosa_vfs_lseek(fd, 0, QOSA_VFS_SEEK_SET)*

- 或重新打开文件

## 文件大小判断不准确

建议读取前先用：

- *qosa_vfs_stat*

- *qosa_vfs_fstat*

先确认文件大小，再按需分配缓冲区。

## 读取接口返回的是“实际读取字节数”

*qosa_vfs_read* 的返回值是实际读到的字节数，不保证一定等于传入的count。

# 为什么删除目录失败？

最常见原因是目录非空。

# 如何查看当前已经挂载的文件系统？

VFS 提供了挂载点查询接口：

- *qosa_vfs_mount_count*

- *qosa_vfs_mount_points*