FS 开发指导_Rev1.2
修订记录
版本 |
日期 |
作者 |
修订内容 |
|---|---|---|---|
Rev1.0 |
23-09-06 |
SXX |
创建文档 |
Rev1.1 |
24-03-25 |
SXX |
更改文档名称 |
Rev1.2 |
24-12-19 |
YMX |
删除函数链接，解决钉钉链接到飞书问题 |
Rev1.3 |
25-02-11 |
LJZ |
修改liot_fopen的文件打开模式 |
1 简介
本文档介绍 LTE-EC71X fs 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_fs/liot_fs_api.h 文件声明。
FS API 提供文件系统操作接口，包括文件打开、关闭、删除、读取、写入、移动、截断、获取文件大小、获取文件信息、获取文件系统剩余空间、获取文件系统信息、获取文件系统目录列表、更改文件名、同步文件数据。
FS 按blockdaxiao块进行管理，文件系统大小为请参考具体的分区表，如：components/basePkg/F6D_A/partition_info.txt，文件系统块大小为4K。不同底包大小不同。
2 API 函数概览
函数 |
说明 |
|---|---|
|
根据文件路径或文件名打开一个文件。 |
|
关闭一个已打开的文件。 |
|
删除一个文件。 |
|
读取文件内容。 |
|
向文件写入内容。 |
|
设置文件指针位置。 |
|
将文件位置指针设置到文件的开头。 |
|
从文件指针位置截断数据。 |
|
根据文件描述符获取文件的状态。 |
|
根据文件名获取文件信息。 |
|
将文件从指定长度截断。 |
|
获取文件大小。 |
|
根据文件名判断文件是否存在。 |
|
创建一个文件夹。 |
|
打开一个文件夹。 |
|
关闭一个已打开的文件夹。 |
|
获取文件夹信息。 |
|
更改文件夹命名。 |
|
同步文件数据。 |
|
获取文件系统剩余大小。 |
3 类型说明
3.1 liot_file_errcode_e
FS API 执行结果错误码。
定义
typedef enum { LIOT_FS_OK = 0, LIOT_FS_INVALID_INPUT_VALUE = -1, /* invalid input value */ LIOT_FS_LARGER_THAN_FILESIZE = -2, /* large than file size */ LIOT_FS_READ_ZERO = -3, /* read zero byte */ LIOT_FS_DRIVE_FULL = -4, /* drive full */ LIOT_FS_MOV_ERROR = -5, /* move error */ LIOT_FS_FILE_NOT_FOUND = -6, /* file not found */ LIOT_FS_INVALID_FILE_NAME = -7, /* invalidate file name*/ LIOT_FS_FILE_ALREADY_EXISTED = -8, /* file already exist */ LIOT_FS_FAILED_TO_CREATE_FILE = -9, /* failed to create file */ LIOT_FS_FAILED_TO_WRITE_FILE = -10, /* failed to write file */ LIOT_FS_FAILED_TO_OPEN_FILE = -11, /* failed to open file */ LIOT_FS_FAILED_TO_READ_FILE = -12, /* failed to read file */ LIOT_FS_EXCEED_MAX_LENGTH = -13, /* exceed max length */ LIOT_FS_REACH_MAX_OPENFILE_NUM = -14, /* reach max opened file num */ LIOT_FS_IS_READONLY = -15, /* file is the read-only */ LIOT_FS_GET_SIZE_FAIL = -16, /* get file size failed */ LIOT_FS_INVALID_FILE_DESCRIPTOR = -17, /* description invalidate */ LIOT_FS_LIST_FILE_FAIL = -18, /* failed to list file */ LIOT_FS_DELETE_FILE_FAIL = -19, /* failed to delete file */ LIOT_FS_GET_DISK_INFO_FAIL = -20, /* failed to get disk info */ LIOT_FS_NO_SPACE = -21, /* disk no space */ LIOT_FS_TIME_OUT = -22, /*time out */ LIOT_FS_FILE_NOT_FOUND_2 = -23, /* file not found */ LIOT_FS_FILE_TOO_LARGE = -24, /* file too large */ LIOT_FS_FILE_ALREADY_EXIST = -25, /* file already exist */ LIOT_FS_INVALID_PARAMETER = -26, /* invalidate parameter */ LIOT_FS_ALREADY_OPERATION = -27, /* file already open */ LIOT_FS_ERROR_GENERAL = -28, LIOT_FS_RENAME_ERROR = -29, LIOT_FS_QUIT_DATE_MODE = -30, LIOT_FS_CLOSE_FAIL = -31, LIOT_FS_SEEK_FAIL = -32, LIOT_FS_TELL_FAIL = -33, LIOT_FS_FAILED_TO_GET_STAT = -34, LIOT_FS_NOT_EXIST = -35, LIOT_FS_RENAME_FAIL = -36, LIOT_FS_TRUNCATE_FAIL = -37, LIOT_FS_DIR_MAKE_FAIL = -38, LIOT_FS_DIR_OPEN_FAIL = -39, LIOT_FS_DIR_CLOSE_FAIL = -40, LIOT_FS_DIR_READ_FAIL = -41, LIOT_FS_DIR_TELL_FAIL = -42, LIOT_FS_DIR_SEEK_FAIL = -43, LIOT_FS_DIR_REMOVE_FAIL = -44, LIOT_FS_DIR_DIR_ALREADY_EXIST = -45, LIOT_FS_ERROR_MAX, } liot_file_errcode_e;
参数
LIOT_FS_OK：API执行成功。
LIOT_FS_INVALID_INPUT_VALUE：输入参数有误。
LIOT_FS_LARGER_THAN_FILESIZE：长度大于文件大小。
LIOT_FS_READ_ZERO：读取0字节。
LIOT_FS_DRIVE_FULL ：文件系统内存已满。
LIOT_FS_MOV_ERROR ：删除文件失败。
LIOT_FS_FILE_NOT_FOUND：文件未找到。
LIOT_FS_INVALID_FILE_NAME：输入文件名不存在。
LIOT_FS_FILE_ALREADY_EXISTED：文件已存在。
LIOT_FS_FAILED_TO_CREATE_FILE：创建文件失败。
LIOT_FS_FAILED_TO_WRITE_FILE ：文件写数据失败。
LIOT_FS_FAILED_TO_OPEN_FILE ：打开文件失败。
LIOT_FS_FAILED_TO_READ_FILE ：读取文件内容失败
LIOT_FS_EXCEED_MAX_LENGTH ：文件超出最大长度
LIOT_FS_REACH_MAX_OPENFILE_NUM ：达到打开文件最大数目
LIOT_FS_IS_READONLY ：文件只读
LIOT_FS_GET_SIZE_FAIL ：获取文件大小失败
LIOT_FS_INVALID_FILE_DESCRIPTOR：文件描述符无效
LIOT_FS_LIST_FILE_FAIL ：获取文件列表失败
LIOT_FS_DELETE_FILE_FAIL ：删除文件失败
LIOT_FS_GET_DISK_INFO_FAIL ：获取文件系统信息失败
LIOT_FS_NO_SPACE ：空间不足
LIOT_FS_TIME_OUT ：超时
LIOT_FS_FILE_NOT_FOUND_2 ：文件未找到
LIOT_FS_FILE_TOO_LARGE ：文件太长
LIOT_FS_FILE_ALREADY_EXIST：文件已存在
LIOT_FS_INVALID_PARAMETER：解析失败
LIOT_FS_ALREADY_OPERATION ：文件已打开
LIOT_FS_ERROR_GENERAL：通用错误
LIOT_FS_RENAME_ERROR ：文件重命名失败
LIOT_FS_QUIT_DATE_MODE ：文件退出数据失败
LIOT_FS_CLOSE_FAIL ：文件关闭失败
LIOT_FS_SEEK_FAIL ：文件设置指针位置失败
LIOT_FS_TELL_FAIL：文件截断失败
LIOT_FS_FAILED_TO_GET_STAT ：获取文件信息失败
LIOT_FS_NOT_EXIST ：文件不存在
LIOT_FS_RENAME_FAIL ：文件重命名失败
LIOT_FS_TRUNCATE_FAIL：截断文件长度失败
LIOT_FS_DIR_MAKE_FAIL：创建文件夹失败
LIOT_FS_DIR_OPEN_FAIL ：文件夹打开失败
LIOT_FS_DIR_CLOSE_FAIL ：文件夹关闭失败
LIOT_FS_DIR_READ_FAIL ：读取文件夹失败
LIOT_FS_DIR_TELL_FAIL
LIOT_FS_DIR_SEEK_FAIL
LIOT_FS_DIR_REMOVE_FAIL
LIOT_FS_DIR_DIR_ALREADY_EXIST ：文件夹已存在
LIOT_FS_ERROR_MAX,
3.2 liot_stat_s
文件信息类型。
定义
typedef struct
{
UINT8 type;
UINT32 size;
CHAR name\[LIOT_FS_NAME_MAX + 1\];
} liot_stat_s;
参数
type：文件类型，0x001：文件类型，0x002：文件夹类型。
参考宏:
#define LIOT_FS_TYPE_FILE 0x001
#define LIOT_FS_TYPE_DIR 0x002
**size：**文件大小。
name: 文件名称 。
3.3 LDIR
文件夹描述符类型。
定义
typedef struct
{
INT32 fs_index; ///< internal fs index
INT32 _reserved; ///< reserved
} LDIR;
参数
fs_index： 内部文件的排序号，即内部文件夹列表的ID号。
_reserved：用户在注册回调时，传入的上下文参数。
3.4 ldirent
文件夹信息类型。
定义
typedef struct
{
INT32 d_info; ///< inode number, file system implementation can use it for any purpose
UINT8 d_type; ///< type of file
CHAR d_name[256]; ///< file name
} ldirent;
参数
d_info： 内部文件的排序号，即内部文件夹列表的ID号。
d_type：文件类型。
d_name：文件夹名称。
4 API 函数详解
4.1 liot_fopen
根据文件路径或文件名打开一个文件。
声明
LFILE liot_fopen(const char *file_name, const char *mode);
参数
file_name：[in] 文件路径或文件名。
mode: [in] 文件打开模式。
r或rb: 以只读文件打开，文件不存在则失败。
r+或rb+: 以读写文件打开，文件不存在则失败。
w或wb: 以只写文件打开，文件存在则清空，不存在则创建。
w+或wb+: 以读写方式打开文件，文件存在则清空，不存在则创建。
a或ab: 以只写追加方式打开文件，文件存在则在末尾追加，不存在则创建。
a+/ab+:以读写追加方式打开文件，文件存在则在末尾追加，不存在则创建。
返回值
LFILE ：文件描述符。
4.2 liot_fclose
关闭一个已打开的文件。
声明
int liot_fclose(LFILE fd);
参数
fd：[in] 文件描述符。
返回值
liot_file_errcode_e: 文件执行错误码，请参考 3.1。
4.3 liot_remove
根据名或文件路径删除文件。
声明
int liot_remove(const char *file_name);
参数
file_name: [in] 文件路径或文件名。
返回值
liot_file_errcode_e: 文件执行错误码，请参考 3.1。
4.4 liot_fread
读取文件内容。
声明
int liot_fread(void *buffer, size_t size, size_t num, LFILE fd);
参数
buffer：[out] 读取到的文件数据。
size：[in] 每次从文件读取的数据的大小。
num: [in] 一共读取几次 size 大小的数据。
fd: [in] 已打开的文件描述符。
返回值
读取到的数据长度。错误时为文件执行错误码，请参考 3.1。
4.5 liot_fwrite
向文件写入内容。
声明
int liot_fwrite(void *buffer, size_t size, size_t num, LFILE fd);
参数
buffer：[in] 写入到文件的数据。
size：[in] 每次从buffer写入到文件的数据大小。
num: [in] 一共写入几次 size 大小的数据。
fd: [in] 已打开的文件描述符。
返回值
成功写入到文件的数据长度。错误时为文件执行错误码，请参考 3.1。
4.6 liot_fseek
设置文件指针位置。
声明
int liot_fseek(LFILE fd, long offset, int origin);
参数
fd: [in] 已打开的文件描述符。
offset: [in] 偏移的长度，正数向后偏移，负数向前偏移。
origin: [in] 偏移的起始位置。
0：文件起始位置。
1：文件当前位置。
2：文件结尾位置。
返回值
当前文件位置，错误为文件执行错误码，请参考 3.1。
4.7 liot_frewind
将文件指针设置到文件开头。
声明
int liot_frewind(LFILE fd);
参数
fd: [in] 已打开的文件描述符。
返回值
文件执行错误码，请参考 3.1。
4.8 liot_ftell
从文件指针位置截断文件。
声明
int liot_ftell(LFILE fd);
参数
fd: [in] 已打开的文件描述符。
返回值
文件执行错误码，请参考 3.1。
4.9 liot_fstat
根据文件描述符获取文件状态。
声明
int liot_fstat(LFILE fd, liot_stat_s *st);
参数
fd: [in] 已打开的文件描述符。
st: [out] liot_stat_s 类型文件状态，请参考 3.2。
返回值
文件执行错误码，请参考 3.1。
4.10 liot_stat
根据文件名称或文件路径获取文件状态。
声明
int liot_stat(const char *file_name, liot_stat_s *st);
参数
file_name: [in] 文件名或文件路径。
st: [out] liot_stat_s 类型文件状态，请参考 3.2。
返回值
文件执行错误码，请参考 3.1。
4.11 liot_ftruncate
将文件从指定位置截断。
声明
int liot_ftruncate(LFILE fd, UINT32 length);
参数
fd: [in] 已打开的文件描述符。
length: [in] 指定的文件长度，从文件起始位置算起
返回值
执行成功返回0，执行失败返回非0值，文件执行错误码，请参考 3.1。
4.12 liot_fsize
获取文件大小。
声明
int liot_fsize(LFILE fd);
参数
fd: [in] 已打开的文件描述符。
返回值
正常返回文件大小，错误时返回文件执行错误码，参考 3.1。
4.13 liot_file_exist
判断文件是否存在。
声明
int liot_file_exist(const char *file_path);
参数
file_path：[in] 文件路径。
返回值
文件执行错误码，请参考 3.1。
存在返回 LIOT_FS_OK，不存在返回 LIOT_FS_NOT_EXIST.
4.14 liot_mkdir
创建一个文件夹。
声明
int liot_mkdir(const char *path, UINT32 mode);
参数
path：[in] 文件夹路径或文件夹名称。
mode: [in] （暂未使用）
返回值
文件执行错误码，请参考 3.1。
4.15 liot_opendir
打开一个文件夹。
声明
LDIR *liot_opendir(const char *path);
参数
path: [in] 文件夹路径或文件夹名称 。
返回值
LDIR 文件夹信息类型描述符，参考3.3。
4.16 liot_closedir
关闭一个打开的文件夹。
声明
int liot_closedir(LDIR *pdir);
参数
pdir：[in] 文件夹类型描述符。
返回值
文件执行错误码，请参考 3.1。
4.17 liot_readdir
获取文件夹信息。
声明
ldirent *liot_readdir(LDIR *pdir);
参数
pdir：[in] 文件夹类型描述符。
返回值
ldirent 类型文件夹信息，参考 3.3。
4.18 liot_rename
更改文件名称。
声明
int liot_rename(const char *oldpath, const char *newpath);
参数
oldpath：[in] 文件路径或文件名称。
newpath：[in] 更改后的文件路径或文件名称。
返回值
文件执行错误码，请参考 3.1。
4.19 liot_fsync
同步文件数据从缓存区到FLASH。
声明
int liot_fsync(LFILE fd);
参数
fd: [in] 已打开的文件描述符。
返回值
文件执行错误码，请参考 3.1。
4.20 liot_internal_fs_free_size_get
获取文件系统剩余大小。
声明
int liot_internal_fs_free_size_get(void);
参数
无。
返回值
当前文件系统剩余可用空间大小。
5 代码示例
示例代码参考 examples/demo/src/demo_fs.c 文件。
运行结果：
