文件系统

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 方式打开文件。

  • 函数原型

qosa_int32_t qosa_vfs_creat(const char *path, qosa_int32_t mode)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

文件路径；必须为绝对路径

mode

输入

qosa_int32_t

文件权限模式

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

qosa_vfs_open

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

  • 函数原型

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

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

  • 函数原型

qosa_int32_t qosa_vfs_close(qosa_int32_t fd)

  • 参数说明

参数名

输入/输出

类型

说明

fd

输入

qosa_int32_t

待关闭的文件描述符

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

qosa_vfs_read

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

  • 函数原型

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

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

  • 函数原型

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

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

  • 函数原型

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

偏移起始位置
QOSA_VFS_SEEK_SET：从文件起始位置偏移
QOSA_VFS_SEEK_CUR：从当前位置偏移
QOSA_VFS_SEEK_END：从文件末尾位置偏移；详见 文件偏移标志

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

qosa_vfs_fstat

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

  • 函数原型

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

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

qosa_vfs_stat

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

  • 函数原型

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

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

qosa_vfs_truncate

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

  • 函数原型

qosa_int32_t qosa_vfs_truncate(const char *path, long length)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

文件路径

length

输入

long

文件截断后的目标长度；单位：字节

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

qosa_vfs_ftruncate

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

  • 函数原型

qosa_int32_t qosa_vfs_ftruncate(qosa_int32_t fd, long length)

  • 参数说明

参数名

输入/输出

类型

说明

fd

输入

qosa_int32_t

文件描述符

length

输入

long

文件截断后的目标长度；单位：字节

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

qosa_vfs_rename

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

  • 函数原型

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

  • 参数说明

参数名

输入/输出

类型

说明

oldpath

输入

const char *

原文件路径

newpath

输入

const char *

新文件路径

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

qosa_vfs_fsync

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

  • 函数原型

qosa_int32_t qosa_vfs_fsync(qosa_int32_t fd)

  • 参数说明

参数名

输入/输出

类型

说明

fd

输入

qosa_int32_t

文件描述符

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

qosa_vfs_file_size

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

  • 函数原型

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() 完成操作。

  • 函数原型

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() 完成操作。

  • 函数原型

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

  • 功能描述
    创建单级目录。

  • 函数原型

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

  • 功能描述
    删除空目录。

  • 函数原型

qosa_int32_t qosa_vfs_rmdir(const char *pathname)

  • 参数说明

参数名

输入/输出

类型

说明

pathname

输入

const char *

待删除的目录路径

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

qosa_vfs_opendir

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

  • 函数原型

QOSA_VFS_DIR *qosa_vfs_opendir(const char *name)

  • 参数说明

参数名

输入/输出

类型

说明

name

输入

const char *

待打开的目录路径

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

qosa_vfs_readdir

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

  • 函数原型

struct qosa_vfs_dirent_t *qosa_vfs_readdir(QOSA_VFS_DIR *dirp)

  • 参数说明

参数名

输入/输出

类型

说明

dirp

输入

*QOSA_VFS_DIR **

由 qosa_vfs_opendir() 返回的目录流指针；详见 QOSA_VFS_DIR

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

qosa_vfs_readdir_r

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

  • 函数原型

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

entry

输出

*struct qosa_vfs_dirent_t **

用于存储读取结果的目录条目缓冲区；详见 qosa_vfs_dirent_t

result

输出

*struct qosa_vfs_dirent_t ***

指向结果指针；成功时指向 entry，到达目录末尾时为 NULL

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

qosa_vfs_closedir

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

  • 函数原型

qosa_int32_t qosa_vfs_closedir(QOSA_VFS_DIR *pdir)

  • 参数说明

参数名

输入/输出

类型

说明

pdir

输入

*QOSA_VFS_DIR **

由 qosa_vfs_opendir() 返回的目录流指针；详见 QOSA_VFS_DIR

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

qosa_vfs_telldir

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

  • 函数原型

long qosa_vfs_telldir(QOSA_VFS_DIR *pdir)

  • 参数说明

参数名

输入/输出

类型

说明

pdir

输入

*QOSA_VFS_DIR **

由 qosa_vfs_opendir() 返回的目录流指针；详见 QOSA_VFS_DIR

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

qosa_vfs_seekdir

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

  • 函数原型

void qosa_vfs_seekdir(QOSA_VFS_DIR *pdir, long loc)

  • 参数说明

参数名

输入/输出

类型

说明

pdir

输入

*QOSA_VFS_DIR **

由 qosa_vfs_opendir() 返回的目录流指针；详见 QOSA_VFS_DIR

loc

输入

long

目标位置；由 qosa_vfs_telldir() 返回

  • 返回值说明
    无

qosa_vfs_rewinddir

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

  • 函数原型

void qosa_vfs_rewinddir(QOSA_VFS_DIR *pdir)

  • 参数说明

参数名

输入/输出

类型

说明

pdir

输入

*QOSA_VFS_DIR **

由 qosa_vfs_opendir() 返回的目录流指针；详见 QOSA_VFS_DIR

  • 返回值说明
    无

qosa_vfs_mkpath

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

  • 函数原型

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

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

  • 函数原型

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

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

  • 函数原型

qosa_int32_t qosa_vfs_rmchildren(const char *path)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

目标目录路径

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

qosa_vfs_rmdir_recursive

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

  • 函数原型

qosa_int32_t qosa_vfs_rmdir_recursive(const char *path)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

待递归删除的目录路径

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

qosa_vfs_chdir

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

  • 函数原型

qosa_int32_t qosa_vfs_chdir(const char *path)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

目标目录路径

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

qosa_vfs_getcwd

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

  • 函数原型

char *qosa_vfs_getcwd(char *buf, qosa_size_t size)

  • 参数说明

参数名

输入/输出

类型

说明

buf

输出

char *

用于存储当前工作目录的缓冲区

size

输入

qosa_size_t

缓冲区大小；单位：字节

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

qosa_vfs_statvfs

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

  • 函数原型

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

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

qosa_vfs_fstatvfs

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

  • 函数原型

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

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

qosa_vfs_mount_count

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

  • 函数原型

qosa_int32_t qosa_vfs_mount_count(void)

  • 参数说明
    无

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

qosa_vfs_mount_points

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

  • 函数原型

qosa_int32_t qosa_vfs_mount_points(char **mp, qosa_size_t count)

  • 参数说明

参数名

输入/输出

类型

说明

mp

输出

char **

用于存储挂载点路径的字符串数组

count

输入

qosa_size_t

数组元素数量

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

qosa_vfs_umount

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

  • 函数原型

qosa_int32_t qosa_vfs_umount(const char *path)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

文件路径；必须为绝对路径（以’/'开头）

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

qosa_vfs_remount

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

  • 函数原型

qosa_int32_t qosa_vfs_remount(const char *path, unsigned flags)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

挂载点路径

flags

输入

unsigned

挂载标志
QOSA_MS_RDONLY：以只读模式重新挂载

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

qosa_vfs_umount_all

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

  • 函数原型

void qosa_vfs_umount_all(void)

  • 参数说明
    无

  • 返回值说明
    无

qosa_vfs_dir_total_size

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

  • 函数原型

qosa_int64_t qosa_vfs_dir_total_size(const char *path)

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

目录路径

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

qosa_vfs_realpath

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

  • 函数原型

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

  • 参数说明

参数名

输入/输出

类型

说明

path

输入

const char *

待解析的文件路径

resolved_path

输出

char *

用于存储规范化绝对路径的缓冲区

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

qosa_vfs_sync

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

  • 函数原型

qosa_int32_t qosa_vfs_sync(qosa_int32_t fd)

  • 参数说明

参数名

输入/输出

类型

说明

fd

输入

qosa_int32_t

待同步的文件描述符

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

结构体定义

qosa_vfs_stat_t

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

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

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

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

成员

说明

fs_index

内部文件系统索引标识

_reserved

保留字段，用于字节对齐或未来扩展

qosa_vfs_dirent_t

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

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

成员

说明

d_ino

inode编号；文件系统实现可自定义用途

d_type

文件类型标识
QOSA_VFS_DT_REG：普通文件
QOSA_VFS_DT_DIR：目录；详见 文件类型标识

d_name

文件名（不含路径部分）；最大256字节

qosa_vfs_statvfs_t

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

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

文件名最大长度

宏定义

文件打开标志

#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

写入数据时从文件末尾追加

文件偏移标志

#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

从文件末尾位置偏移

文件类型标识

#define QOSA_VFS_DT_DIR      4  
#define QOSA_VFS_DT_REG      8

宏名

值

说明

QOSA_VFS_DT_DIR

4

目录

QOSA_VFS_DT_REG

8

普通文件

路径长度限制

#define QOSA_VFS_PATH_MAX    192

宏名

值

说明

QOSA_VFS_PATH_MAX

192

最大绝对文件路径长度（含挂载点和终止符\0）

应用逻辑流程图

文件操作流程

image

目录操作流程

image

示例代码

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