unistd

POSIX 标准操作系统 API 接口模块，提供文件操作、目录操作、进程控制、系统配置等基础系统调用功能。

头文件清单

#include "open_source/musl/include/unistd.h"

接口清单

接口名称	功能简述
access	判断文件权限
chdir	改变当前工作目录
close	关闭文件
dup	复制文件描述符
dup2	复制文件描述符到指定描述符
fsync	文件同步
ftruncate	改变文件大小
getcwd	获取当前工作目录
getopt	分析命令行参数
getpid	获取任务ID
isatty	判断文件描述符是否为终端设备
lseek	改变文件读写指针位置
pread	从指定偏移位置读文件
pwrite	从指定偏移位置写文件
read	读文件
rmdir	删除目录
sleep	以秒为单位阻塞进程
sync	将文件系统缓存数据写入存储设备
sysconf	获取系统参数
unlink	删除文件
write	写文件

Functions

access

int access(const char *, int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

检查指定路径文件的访问权限
根据传入的模式参数（R_OK/W_OK/X_OK/F_OK）判断文件是否具有对应权限
检查文件是否存在及对应权限位是否满足

入参

名称	参数类型	详细说明	约束取值范围
path	const char *	待检查权限的文件路径	非NULL，有效路径字符串
amode	int	检查的权限模式	- F_OK（文件是否存在） - R_OK（读权限） - W_OK（写权限） - X_OK（执行权限）

返回值

返回值	文字含义	触发场景
0	文件具有指定权限	文件存在且具有amode指定的权限
-1	文件不具有指定权限或文件不存在	文件不存在或权限检查不通过

chdir

int chdir(const char *)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

前置条件

调用时序约束：文件系统已初始化
依赖关系：依赖VFS已挂载且工作目录功能已启用（VFS_USING_WORKDIR）

入参

名称	参数类型	详细说明	约束取值范围
path	const char *	目标目录路径	非NULL，长度不超过PATH_MAX，目标必须为已存在的目录

返回值

返回值	文字含义	触发场景
0	工作目录切换成功	路径有效且目录存在
-1	工作目录切换失败	路径无效、目录不存在或目标不是目录

close

int close(int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

关闭指定的文件描述符，释放相关资源
若为socket描述符则调用socket关闭流程
关闭后文件描述符可被复用

入参

名称	参数类型	详细说明	约束取值范围
fd	int	待关闭的文件描述符	有效的已打开文件描述符

返回值

返回值	文字含义	触发场景
0	文件关闭成功	文件描述符合法且关闭操作成功
-1	文件关闭失败	文件描述符无效或关闭操作失败

dup

int dup(int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

复制一个已打开的文件描述符，返回新的文件描述符
新文件描述符为当前可用最小值
新旧描述符指向同一文件，共享文件偏移量

入参

名称	参数类型	详细说明	约束取值范围
fd	int	待复制的文件描述符	有效的已打开文件描述符

返回值

返回值	文字含义	触发场景
非负整数	新文件描述符	复制成功
-1	复制失败	文件描述符无效或系统资源不足

dup2

int dup2(int, int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

将文件描述符复制到指定的目标描述符编号
若目标描述符已打开则先关闭再复制
新旧描述符指向同一文件，共享文件偏移量

入参

名称	参数类型	详细说明	约束取值范围
fd1	int	源文件描述符	有效的已打开文件描述符
fd2	int	目标文件描述符	有效的文件描述符编号

返回值

返回值	文字含义	触发场景
非负整数	新文件描述符（等于fd2）	复制成功
-1	复制失败	源描述符无效或操作失败

fsync

int fsync(int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

将指定文件描述符对应的文件数据及元数据同步到存储设备
确保文件修改内容持久化到磁盘

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符

返回值

返回值	文字含义	触发场景
0	同步成功	文件数据已成功写入存储设备
-1	同步失败	文件描述符无效或同步操作失败

ftruncate

int ftruncate(int, off_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

改变指定文件描述符对应文件的大小
若新大小大于当前大小则扩展文件（填充零字节）
若新大小小于当前大小则截断文件

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符，需以写模式打开
length	off_t	目标文件大小	`0 ~ LONG_MAX`

返回值

返回值	文字含义	触发场景
0	文件大小修改成功	参数合法且截断操作成功
-1	文件大小修改失败	文件描述符无效、length为负值或操作失败

getcwd

char *getcwd(char *, size_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

获取当前工作目录的绝对路径
将路径字符串写入用户提供的缓冲区
支持多线程安全访问工作目录

前置条件

调用时序约束：文件系统已初始化
依赖关系：依赖VFS_USING_WORKDIR宏已开启

出参

名称	数据类型	输出说明
buf	char *	当前工作目录的绝对路径字符串

入参

名称	参数类型	详细说明	约束取值范围
n	size_t	缓冲区大小	大于当前工作目录路径字符串长度

返回值

返回值	文字含义	触发场景
char *	指向buf的指针	成功获取当前工作目录
NULL	获取失败	buf为NULL或缓冲区大小不足

getopt

int getopt(int, char * const [], const char *)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

解析命令行参数中的选项字符
支持短选项（单字符选项）解析，支持带参数选项
通过全局变量optarg、optind、opterr、optopt提供解析状态

入参

名称	参数类型	详细说明	约束取值范围
argc	int	命令行参数个数	与argv对应
argv	char * const []	命令行参数数组	非NULL
optstring	const char *	选项字符串，定义合法选项字符	非NULL，冒号表示选项需要参数

返回值

返回值	文字含义	触发场景
选项字符	当前解析到的选项字符	选项在optstring中定义
-1	选项解析结束	所有选项已解析完毕
'?'	遇到无法识别的选项	选项不在optstring中或缺少参数

getpid

pid_t getpid(void)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

获取当前任务的ID
返回值类型为pid_t，对应LiteOS中的任务ID
返回当前运行任务的标识

返回值

返回值	文字含义	触发场景
pid_t	当前任务ID	成功获取当前任务ID

isatty

int isatty(int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

判断指定文件描述符是否为终端设备
当前LiteOS实现始终返回0，表示非终端设备
用于POSIX兼容性检查

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的文件描述符

返回值

返回值	文字含义	触发场景
0	不是终端设备	LiteOS中始终返回0
1	是终端设备	标准POSIX定义，当前LiteOS不支持

lseek

off_t lseek(int, off_t, int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

改变已打开文件的读写偏移位置
支持三种定位方式：文件起始、当前位置、文件末尾
返回新的文件偏移位置

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
offset	off_t	偏移量	根据whence决定含义
whence	int	定位基准	- SEEK_SET（文件起始位置） - SEEK_CUR（当前位置） - SEEK_END（文件末尾）

返回值

返回值	文字含义	触发场景
非负off_t	新的文件偏移位置	定位成功
-1	定位失败	文件描述符无效或whence参数非法

pread

ssize_t pread(int, void *, size_t, off_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

从文件的指定偏移位置读取数据，不改变文件当前偏移量
原子性完成定位和读取操作
适用于多线程环境下对同一文件的并发读取

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
count	size_t	请求读取的字节数	`0 ~ SSIZE_MAX`
offset	off_t	读取起始偏移量	`0 ~ 文件大小`

出参

名称	数据类型	输出说明
buf	void *	读取到的文件数据

返回值

返回值	文字含义	触发场景
非负ssize_t	实际读取的字节数	读取成功
-1	读取失败	文件描述符无效、offset非法或读取错误

pwrite

ssize_t pwrite(int, const void *, size_t, off_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

从指定偏移位置向文件写入数据，不改变文件当前偏移量
原子性完成定位和写入操作
适用于多线程环境下对同一文件的并发写入

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
buf	const void *	待写入数据的缓冲区	非NULL
count	size_t	请求写入的字节数	`0 ~ SSIZE_MAX`
offset	off_t	写入起始偏移量	`0 ~ 文件大小`

返回值

返回值	文字含义	触发场景
非负ssize_t	实际写入的字节数	写入成功
-1	写入失败	文件描述符无效、offset非法或写入错误

read

ssize_t read(int, void *, size_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

从文件描述符指向的文件中读取数据
从文件当前偏移位置开始读取，读取后偏移量前移
返回实际读取的字节数

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
count	size_t	请求读取的字节数	`0 ~ SSIZE_MAX`

出参

名称	数据类型	输出说明
buf	void *	读取到的文件数据

返回值

返回值	文字含义	触发场景
非负ssize_t	实际读取的字节数	读取成功
0	已到达文件末尾	无更多数据可读
-1	读取失败	文件描述符无效或读取错误

rmdir

int rmdir(const char *)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

删除指定的空目录
仅当目录为空时才能成功删除
通过VFS层调用底层文件系统的rmdir操作

入参

名称	参数类型	详细说明	约束取值范围
pathname	const char *	待删除目录的路径	非NULL，指向已存在的空目录

返回值

返回值	文字含义	触发场景
0	目录删除成功	目录为空且删除操作成功
-1	目录删除失败	目录不存在、目录非空或权限不足

sleep

unsigned sleep(unsigned)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

使当前任务以秒为单位休眠
内部通过nanosleep实现，将秒转换为纳秒级精度
若被信号中断则返回剩余未休眠的秒数

入参

名称	参数类型	详细说明	约束取值范围
seconds	unsigned int	休眠时间（秒）	`0 ~ UINT_MAX`

返回值

返回值	文字含义	触发场景
0	休眠完整完成	指定时间已全部休眠
非零值	剩余未休眠的秒数	休眠被信号中断

sync

void sync(void)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

将所有文件系统缓存中的修改数据写入存储设备
确保文件系统数据与存储设备一致
在LiteOS中依赖LOSCFG_FS_FAT_CACHE配置

前置条件

依赖关系：依赖LOSCFG_FS_FAT_CACHE宏开启FAT缓存功能时生效

sysconf

long sysconf(int)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

获取系统配置参数值
支持查询_POSIX相关系统限制参数（如页面大小、最大打开文件数等）
根据传入的name参数返回对应的系统配置值

入参

名称	参数类型	详细说明	约束取值范围
name	int	系统配置参数名	SC*系列宏值（如_SC_PAGESIZE、_SC_OPEN_MAX等）

返回值

返回值	文字含义	触发场景
非负long	对应系统参数的值	参数名合法
-1	参数名无效或不支持	name不在支持范围内

unlink

int unlink(const char *)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

删除指定路径的文件
若文件为符号链接则删除链接本身
通过VFS层调用底层文件系统的unlink操作

入参

名称	参数类型	详细说明	约束取值范围
pathname	const char *	待删除文件的路径	非NULL，指向已存在的文件

返回值

返回值	文字含义	触发场景
0	文件删除成功	文件存在且删除操作成功
-1	文件删除失败	文件不存在或权限不足

write

ssize_t write(int, const void *, size_t)

头文件清单

#include "open_source/musl/include/unistd.h"

功能说明

向文件描述符指向的文件写入数据
从文件当前偏移位置开始写入，写入后偏移量前移
返回实际写入的字节数

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
buf	const void *	待写入数据的缓冲区	非NULL
count	size_t	请求写入的字节数	`0 ~ SSIZE_MAX`

返回值

返回值	文字含义	触发场景
非负ssize_t	实际写入的字节数	写入成功
-1	写入失败	文件描述符无效或写入错误

Macros

STDIN_FILENO

#define STDIN_FILENO  0

STDOUT_FILENO

#define STDOUT_FILENO 1

STDERR_FILENO

#define STDERR_FILENO 2

SEEK_SET

#define SEEK_SET 0

SEEK_CUR

#define SEEK_CUR 1

SEEK_END

#define SEEK_END 2

F_OK

#define F_OK 0

R_OK

#define R_OK 4

W_OK

#define W_OK 2

X_OK

#define X_OK 1