Fileops

内核级文件 I/O 抽象层（klib），提供标准 POSIX 风格文件操作：open、close、read、write、fsync（刷写）、seek（定位）、unlink（删除）和 truncate（截断）。

定义标准文件打开标志（O_RDONLY/O_WRONLY/O_RDWR/O_CREAT/O_TRUNC/O_APPEND 等）和寻址模式。适用 LittleFS 等文件系统上的文件读写。

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

接口清单

接口名称功能简述

osal_klib_fopen 打开文件并返回文件指针

osal_klib_fclose 关闭文件

osal_klib_fwrite 向文件写入数据

osal_klib_fread 从文件读取数据

osal_klib_fsync 将文件数据同步到存储设备

osal_klib_fseek 设置文件读写位置

osal_klib_unlink 删除文件或空目录

osal_klib_ftruncate 将文件截断到指定长度

Functions

osal_klib_fopen

void *osal_klib_fopen(const char *file, int flags, int mode)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

打开指定路径的文件，根据标志位和模式参数控制文件的打开方式
返回文件指针用于后续文件操作接口的入参
文件指针由内核动态分配内存管理，调用者需通过 osal_klib_fclose 释放

前置条件

文件系统已初始化且可访问
入参 file 不为 NULL

入参

名称参数类型详细说明约束取值范围

file const char * 文件路径字符串非 NULL

flags int 文件操作标志，控制打开方式 OSAL_O_RDONLY(0), OSAL_O_WRONLY(1), OSAL_O_RDWR(2), OSAL_O_CREAT(64), OSAL_O_EXCL(128), OSAL_O_TRUNC(512), OSAL_O_APPEND(1024), OSAL_O_CLOEXEC(0x800000)

mode int 文件权限模式 OSAL_O_RDONLY(0), OSAL_O_WRONLY(1), OSAL_O_RDWR(2)

返回值

返回类型：void *

返回值文字含义触发场景

非 NULL 指针文件打开成功文件路径合法且文件系统可用

NULL 文件打开失败文件路径为 NULL、文件不存在且未指定 OSAL_O_CREAT、存储空间不足

osal_klib_fclose

void osal_klib_fclose(void *filp)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

关闭由 osal_klib_fopen 打开的文件
释放文件指针占用的内核内存资源
关闭后 filp 指针不可再用于其他文件操作接口

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针

入参

名称参数类型详细说明约束取值范围

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

osal_klib_fwrite

int osal_klib_fwrite(const char *buf, unsigned long size, void *filp)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

将缓冲区数据写入文件
从当前文件读写位置开始写入，写入完成后读写位置自动后移
返回实际写入的字节数

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针
文件以写模式（OSAL_O_WRONLY 或 OSAL_O_RDWR）打开

入参

名称参数类型详细说明约束取值范围

buf const char * 待写入数据缓冲区非 NULL

size unsigned long 待写入数据字节数 > 0

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

返回值

返回类型：int

返回值文字含义触发场景

> 0 实际写入的字节数写入成功

OSAL_FAILURE(-1) 写入失败 filp 或 buf 为 NULL

osal_klib_fread

int osal_klib_fread(char *buf, unsigned long size, void *filp)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

从文件读取数据到缓冲区
从当前文件读写位置开始读取，读取完成后读写位置自动后移
返回实际读取的字节数

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针
文件以读模式（OSAL_O_RDONLY 或 OSAL_O_RDWR）打开

入参

名称参数类型详细说明约束取值范围

buf char * 读取数据存放缓冲区非 NULL，缓冲区长度不小于 size

size unsigned long 待读取数据字节数 > 0

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

返回值

返回类型：int

返回值文字含义触发场景

> 0 实际读取的字节数读取成功

OSAL_FAILURE(-1) 读取失败 filp 或 buf 为 NULL

osal_klib_fsync

void osal_klib_fsync(void *filp)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

将文件缓存数据同步到存储设备
确保数据持久化写入底层存储介质
仅支持 linux、liteos 系统

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针
文件已写入数据且需持久化

入参

名称参数类型详细说明约束取值范围

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

osal_klib_fseek

int osal_klib_fseek(long long offset, int whence, void *filp)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

设置文件读写位置偏移量
根据 whence 参数确定偏移基准位置
offset 值超过 INT32_MAX 时返回 OSAL_EOVERFLOW

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针

入参

名称参数类型详细说明约束取值范围

offset long long 偏移量 offset 不超过 INT32_MAX

whence int 偏移基准位置 OSAL_SEEK_SET(0), OSAL_SEEK_CUR(1), OSAL_SEEK_END(2)

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

返回值

返回类型：int

返回值文字含义触发场景

>= 0 新的文件读写位置设置成功

OSAL_FAILURE(-1) 设置失败 filp 为 NULL 或 offset 超过 INT32_MAX

OSAL_EOVERFLOW(-75) 偏移结果溢出 lseek 返回值超过 int 表达范围

参考案例

src/middleware/services/srv_tiot_host/tiot_driver/common/utils/fileops/tiot_fileops.c

osal_klib_unlink

int osal_klib_unlink(const char *path)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

删除指定路径的文件或目录
删除目录时目录必须为空，否则操作失败
仅支持 seliteos 系统

前置条件

文件系统已挂载且可访问
入参 path 不为 NULL
若删除目录，目录必须为空

入参

名称参数类型详细说明约束取值范围

path const char * 文件或目录路径字符串非 NULL

返回值

返回类型：int

返回值文字含义触发场景

0 删除成功文件或空目录删除成功

其他值删除失败路径不存在、目录非空、权限不足

osal_klib_ftruncate

int osal_klib_ftruncate(void *filp, unsigned long len)

头文件清单

#include "kernel/osal/include/fileops/osal_fileops.h"

功能说明

将文件大小截断到指定长度
若指定长度小于当前文件大小，超出部分数据被丢弃
若指定长度大于当前文件大小，文件扩展并以未定义内容填充
仅支持 seliteos 系统

前置条件

filp 为 osal_klib_fopen 返回的有效文件指针
文件以写模式打开

入参

名称参数类型详细说明约束取值范围

filp void * 文件指针 osal_klib_fopen 返回的有效指针，非 NULL

len unsigned long 目标文件长度 > 0

返回值

返回类型：int

返回值文字含义触发场景

0 截断成功文件大小调整成功

其他值截断失败 filp 无效、文件系统错误

Type definitions

文件指针类型别名

// 文件操作统一使用 void * 作为文件指针类型
// 由 osal_klib_fopen 返回，传入其他文件操作接口使用

使用说明：作为 osal_klib_fopen 返回值及 osal_klib_fclose、osal_klib_fwrite、osal_klib_fread、osal_klib_fsync、osal_klib_fseek、osal_klib_ftruncate 的入参使用

Enumerations

文件打开标志

// 文件操作标志定义
#define OSAL_O_RDONLY 00000000
#define OSAL_O_WRONLY 00000001
#define OSAL_O_RDWR   00000002
#define OSAL_O_ACCMODE 00000003
#define OSAL_O_CREAT  00000100
#define OSAL_O_EXCL   00000200
#define OSAL_O_TRUNC  00001000
#define OSAL_O_APPEND 00002000
#define OSAL_O_CLOEXEC 02000000

枚举成员取值描述

OSAL_O_RDONLY 0 只读打开

OSAL_O_WRONLY 1 只写打开

OSAL_O_RDWR 2 读写打开

OSAL_O_ACCMODE 3 访问模式掩码

OSAL_O_CREAT 64 文件不存在时创建

OSAL_O_EXCL 128 与 OSAL_O_CREAT 同用时，文件已存在则失败

OSAL_O_TRUNC 512 截断文件为0长度

OSAL_O_APPEND 1024 追加写入

OSAL_O_CLOEXEC 0x800000 执行时关闭文件描述符

文件偏移基准

// 文件偏移基准位置定义
#define OSAL_SEEK_SET 0
#define OSAL_SEEK_CUR 1
#define OSAL_SEEK_END 2

枚举成员取值描述

OSAL_SEEK_SET 0 从文件起始位置偏移

OSAL_SEEK_CUR 1 从当前读写位置偏移

OSAL_SEEK_END 2 从文件末尾位置偏移

接口名称	功能简述
osal_klib_fopen	打开文件并返回文件指针
osal_klib_fclose	关闭文件
osal_klib_fwrite	向文件写入数据
osal_klib_fread	从文件读取数据
osal_klib_fsync	将文件数据同步到存储设备
osal_klib_fseek	设置文件读写位置
osal_klib_unlink	删除文件或空目录
osal_klib_ftruncate	将文件截断到指定长度

名称	参数类型	详细说明	约束取值范围
file	const char *	文件路径字符串	非 NULL
flags	int	文件操作标志，控制打开方式	OSAL_O_RDONLY(0), OSAL_O_WRONLY(1), OSAL_O_RDWR(2), OSAL_O_CREAT(64), OSAL_O_EXCL(128), OSAL_O_TRUNC(512), OSAL_O_APPEND(1024), OSAL_O_CLOEXEC(0x800000)
mode	int	文件权限模式	OSAL_O_RDONLY(0), OSAL_O_WRONLY(1), OSAL_O_RDWR(2)

返回值	文字含义	触发场景
非 NULL 指针	文件打开成功	文件路径合法且文件系统可用
NULL	文件打开失败	文件路径为 NULL、文件不存在且未指定 OSAL_O_CREAT、存储空间不足

名称	参数类型	详细说明	约束取值范围
buf	const char *	待写入数据缓冲区	非 NULL
size	unsigned long	待写入数据字节数	> 0
filp	void *	文件指针	osal_klib_fopen 返回的有效指针，非 NULL

返回值	文字含义	触发场景
> 0	实际写入的字节数	写入成功
OSAL_FAILURE(-1)	写入失败	filp 或 buf 为 NULL

名称	参数类型	详细说明	约束取值范围
buf	char *	读取数据存放缓冲区	非 NULL，缓冲区长度不小于 size
size	unsigned long	待读取数据字节数	> 0
filp	void *	文件指针	osal_klib_fopen 返回的有效指针，非 NULL

返回值	文字含义	触发场景
> 0	实际读取的字节数	读取成功
OSAL_FAILURE(-1)	读取失败	filp 或 buf 为 NULL

名称	参数类型	详细说明	约束取值范围
offset	long long	偏移量	offset 不超过 INT32_MAX
whence	int	偏移基准位置	OSAL_SEEK_SET(0), OSAL_SEEK_CUR(1), OSAL_SEEK_END(2)
filp	void *	文件指针	osal_klib_fopen 返回的有效指针，非 NULL

返回值	文字含义	触发场景
>= 0	新的文件读写位置	设置成功
OSAL_FAILURE(-1)	设置失败	filp 为 NULL 或 offset 超过 INT32_MAX
OSAL_EOVERFLOW(-75)	偏移结果溢出	lseek 返回值超过 int 表达范围

返回值	文字含义	触发场景
0	删除成功	文件或空目录删除成功
其他值	删除失败	路径不存在、目录非空、权限不足

返回值	文字含义	触发场景
0	截断成功	文件大小调整成功
其他值	截断失败	filp 无效、文件系统错误

枚举成员	取值	描述
OSAL_O_RDONLY	0	只读打开
OSAL_O_WRONLY	1	只写打开
OSAL_O_RDWR	2	读写打开
OSAL_O_ACCMODE	3	访问模式掩码
OSAL_O_CREAT	64	文件不存在时创建
OSAL_O_EXCL	128	与 OSAL_O_CREAT 同用时，文件已存在则失败
OSAL_O_TRUNC	512	截断文件为0长度
OSAL_O_APPEND	1024	追加写入
OSAL_O_CLOEXEC	0x800000	执行时关闭文件描述符

枚举成员	取值	描述
OSAL_SEEK_SET	0	从文件起始位置偏移
OSAL_SEEK_CUR	1	从当前读写位置偏移
OSAL_SEEK_END	2	从文件末尾位置偏移