time

time 模块提供 POSIX 标准的时间相关接口，包括时间获取、时间转换、定时器管理、高精度睡眠等功能。

头文件清单

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

接口清单

接口名称	功能简述
asctime_r	将时间和日期以字符串形式表示
clock_getres	获取对应时钟类型能够提供的时间精确度
clock_gettime	获取指定时钟的时间
clock_settime	设置指定时钟的时间
clock_nanosleep	具有可指定时钟的高分辨率睡眠
ctime_r	将时间和日期以字符串形式表示
gmtime_r	取得目前的时间和日期
localtime_r	取得当地目前的时间和日期
nanosleep	进程以纳秒为单位休眠
strftime_l	格式化日期和时间
strptime	按照特定时间格式将字符串转换为时间类型
timer_create	创建定时器
timer_delete	删除定时器
timer_getoverrun	获取定时器超时次数
timer_gettime	获得一个定时器剩余时间
timer_settime	初始化或者撤销定时器

Functions

asctime_r

函数声明

char *asctime_r(const struct tm *__restrict, char *__restrict)

头文件清单

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

功能说明

• 将struct tm结构体中的时间信息转换为可读的字符串格式
• 转换结果写入用户提供的缓冲区中，线程安全
• 输出格式为"Weekday Month Day HH:MM:SS Year\n"

入参

名称	参数类型	详细说明	约束取值范围
tm	const struct tm *__restrict	指向待转换的时间结构体的指针	非NULL

出参

名称	数据类型	输出说明
buf	char *__restrict	写入格式化后的时间字符串，缓冲区大小不小于26字节

返回值

返回值	文字含义	触发场景
非NULL指针	成功返回buf指针	转换成功
NULL	转换失败	tm中字段超出有效范围

clock_getres

clock getres clock_getres

函数声明

int clock_getres(clockid_t, struct timespec *)

头文件清单

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

功能说明

• 获取指定时钟类型的分辨率（精确度）
• 将时钟分辨率写入tp指向的timespec结构体
• 仅支持CLOCK_REALTIME时钟类型

前置条件

• 调用时序约束：需在系统时钟初始化完成后调用
• 依赖关系：依赖系统时钟已正常工作

入参

名称	参数类型	详细说明	约束取值范围
clockId	clockid_t	时钟类型标识	CLOCK_REALTIME(0)

出参

名称	数据类型	输出说明
tp	struct timespec *	写入时钟分辨率信息，tv_sec为0，tv_nsec为1000（1微秒），需非NULL

返回值

返回值	文字含义	触发场景
0	执行成功	参数合法
-1	执行失败	clockId不是CLOCK_REALTIME或tp为NULL，errno置为EINVAL

clock_gettime

clock gettime clock_gettime

函数声明

int clock_gettime(clockid_t, struct timespec *)

头文件清单

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

功能说明

• 获取指定时钟的当前时间
• 支持CLOCK_REALTIME、CLOCK_MONOTONIC、CLOCK_MONOTONIC_RAW三种时钟类型
• 将时间信息写入tp指向的timespec结构体

前置条件

• 调用时序约束：需在系统时钟初始化完成后调用
• 依赖关系：依赖系统tick时钟已正常工作

入参

名称	参数类型	详细说明	约束取值范围
clockId	clockid_t	时钟类型标识	- CLOCK_REALTIME(0) - CLOCK_MONOTONIC(1) - CLOCK_MONOTONIC_RAW(4)

出参

名称	数据类型	输出说明
tp	struct timespec *	写入当前时钟时间信息，需非NULL

返回值

返回值	文字含义	触发场景
0	执行成功	参数合法，获取时间成功
-1	执行失败	clockId超出有效范围或tp为NULL，errno置为EINVAL

clock_settime

clock settime clock_settime

函数声明

int clock_settime(clockid_t, const struct timespec *)

头文件清单

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

功能说明

• 设置指定时钟的时间
• 仅支持CLOCK_REALTIME时钟类型
• 设置的时间通过tp指向的timespec结构体传入

前置条件

• 调用时序约束：需在系统时钟初始化完成后调用
• 依赖关系：依赖系统时钟已正常工作
• 调用上下文约束：需在任务上下文调用，禁止在中断上下文调用

入参

名称	参数类型	详细说明	约束取值范围
clockId	clockid_t	时钟类型标识	CLOCK_REALTIME(0)
tp	const struct timespec *	指向待设置时间信息的结构体指针	非NULL，tv_nsec范围0~999999999，tv_sec不小于0

返回值

返回值	文字含义	触发场景
0	执行成功	参数合法，设置时间成功
-1	执行失败	clockId不是CLOCK_REALTIME或tp参数无效，errno置为EINVAL

clock_nanosleep

clock nanosleep clock_nanosleep

函数声明

int clock_nanosleep(clockid_t, int, const struct timespec *, struct timespec *)

头文件清单

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

功能说明

• 具有可指定时钟的高分辨率睡眠功能
• 目前只支持CLOCK_REALTIME时钟
• flags为0时使用相对时间睡眠，flags为TIMER_ABSTIME时使用绝对时间

前置条件

• 调用时序约束：需在系统时钟初始化完成后调用
• 依赖关系：依赖nanosleep接口可正常工作

入参

名称	参数类型	详细说明	约束取值范围
clk	clockid_t	时钟类型标识	CLOCK_REALTIME(0)
flags	int	睡眠模式标志	- 0：相对时间 - TIMER_ABSTIME(1)：绝对时间
req	const struct timespec *	指向睡眠时间信息的结构体指针	非NULL，tv_nsec范围0~999999999，tv_sec不小于0

出参

名称	数据类型	输出说明
rem	struct timespec *	写入剩余时间信息，可为NULL

返回值

返回值	文字含义	触发场景
0	睡眠完成	指定时间已到
EINVAL	参数无效	clk无效或flags非法
ENOTSUP	不支持	指定时钟类型不支持绝对时间睡眠

ctime_r

函数声明

char *ctime_r(const time_t *, char *)

头文件清单

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

功能说明

• 将time_t时间值转换为可读的本地时间字符串
• 转换结果写入用户提供的缓冲区中，线程安全
• 内部调用localtime_r和asctime_r完成转换

入参

名称	参数类型	详细说明	约束取值范围
t	const time_t *	指向待转换的时间值的指针	非NULL

出参

名称	数据类型	输出说明
buf	char *	写入格式化后的本地时间字符串，缓冲区大小不小于26字节

返回值

返回值	文字含义	触发场景
非NULL指针	成功返回buf指针	转换成功
NULL	转换失败	时间值无法转换为有效本地时间

gmtime_r

函数声明

struct tm *gmtime_r(const time_t *__restrict, struct tm *__restrict)

头文件清单

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

功能说明

• 将time_t时间值转换为UTC时间的struct tm结构体
• 转换结果写入用户提供的结构体中，线程安全
• 转换后的tm_isdst置为0，tm_gmtoff置为0，tm_zone置为"UTC"

入参

名称	参数类型	详细说明	约束取值范围
t	const time_t *__restrict	指向待转换的时间值的指针	非NULL

出参

名称	数据类型	输出说明
tm	struct tm *__restrict	写入UTC时间结构体信息，需非NULL

返回值

返回值	文字含义	触发场景
非NULL指针	成功返回tm指针	转换成功
NULL	转换失败	时间值超出可表示范围，errno置为EOVERFLOW

localtime_r

函数声明

struct tm *localtime_r(const time_t *__restrict, struct tm *__restrict)

头文件清单

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

功能说明

• 将time_t时间值转换为本地时间的struct tm结构体
• 转换结果写入用户提供的结构体中，线程安全
• 考虑时区和夏令时偏移进行转换

入参

名称	参数类型	详细说明	约束取值范围
t	const time_t *__restrict	指向待转换的时间值的指针	非NULL

出参

名称	数据类型	输出说明
tm	struct tm *__restrict	写入本地时间结构体信息，tm_gmtoff为时区偏移，需非NULL

返回值

返回值	文字含义	触发场景
非NULL指针	成功返回tm指针	转换成功
NULL	转换失败	时间值超出可表示范围，errno置为EOVERFLOW

nanosleep

函数声明

int nanosleep(const struct timespec *, struct timespec *)

头文件清单

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

功能说明

• 使当前进程以纳秒级精度休眠
• 目前只支持tick级（默认10ms）休眠精度
• 第二个参数rmtp不支持，传入的值将被忽略
• 休眠秒数不能大于4292秒

前置条件

• 调用时序约束：需在系统tick时钟初始化完成后调用
• 调用上下文约束：需在任务上下文调用，禁止在中断上下文调用

入参

名称	参数类型	详细说明	约束取值范围
rqtp	const struct timespec *	指向休眠时间信息的结构体指针	非NULL，tv_nsec范围0~999999999，tv_sec不小于0且不超过4292

出参

名称	数据类型	输出说明
rmtp	struct timespec *	存放剩余时间信息的结构体指针（当前不支持，传入值将被忽略）

返回值

返回值	文字含义	触发场景
0	休眠完成	指定时间已到
-1	执行失败	参数无效，errno置为EINVAL；或无权限，errno置为EPERM

strftime_l

函数声明

size_t strftime_l(char *__restrict, size_t, const char *__restrict, const struct tm *__restrict, locale_t)

头文件清单

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

功能说明

• 根据指定区域设置格式化日期和时间
• 将struct tm结构体中的时间信息按format格式字符串转换为字符串
• 格式化字符不支持%z或%Z的格式化转换
• 支持locale_t参数指定区域设置

入参

名称	参数类型	详细说明	约束取值范围
maxsize	size_t	输出缓冲区的大小	大于0
format	const char *__restrict	格式化字符串	非NULL
tm	const struct tm *__restrict	指向待格式化的时间结构体指针	非NULL
loc	locale_t	区域设置	有效的locale_t值

出参

名称	数据类型	输出说明
s	char *__restrict	写入格式化后的时间字符串，需非NULL

返回值

返回值	文字含义	触发场景
非零值	成功写入的字符数（不含结尾\0）	格式化成功
0	缓冲区空间不足	maxsize不足或格式化结果为空

strptime

函数声明

char *strptime(const char *__restrict, const char *__restrict, struct tm *__restrict)

头文件清单

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

功能说明

• 按照特定时间格式将字符串转换为struct tm时间结构体
• 解析输入字符串s中的时间信息，按format格式字符串进行匹配
• 支持常见的日期和时间格式化占位符

入参

名称	参数类型	详细说明	约束取值范围
s	const char *__restrict	指向待解析的时间字符串指针	非NULL
f	const char *__restrict	格式化字符串指针	非NULL

出参

名称	数据类型	输出说明
tm	struct tm *__restrict	写入解析后的时间结构体信息，需非NULL

返回值

返回值	文字含义	触发场景
非NULL指针	成功返回未解析部分的指针	解析成功
NULL	解析失败	字符串与格式不匹配

timer_create

函数声明

int timer_create(clockid_t, struct sigevent *__restrict, timer_t *__restrict)

头文件清单

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

功能说明

• 创建一个POSIX定时器
• 只支持SIGEV_THREAD在线程内处理定时器回调
• clock_id只支持CLOCK_REALTIME
• 定时器创建后处于停止状态，需调用timer_settime启动

前置条件

• 调用时序约束：需在系统软件定时器模块初始化完成后调用
• 依赖关系：依赖LiteOS软件定时器资源可用
• 调用上下文约束：需在任务上下文调用，禁止在中断上下文调用

入参

名称	参数类型	详细说明	约束取值范围
clockId	clockid_t	时钟类型标识	CLOCK_REALTIME(0)
evp	struct sigevent *__restrict	指向定时器事件配置结构体的指针	非NULL，sigev_notify必须为SIGEV_THREAD

出参

名称	数据类型	输出说明
timerId	timer_t *__restrict	写入创建的定时器标识，需非NULL

返回值

返回值	文字含义	触发场景
0	创建成功	参数合法，定时器资源可用
-1	创建失败	clockId不是CLOCK_REALTIME或evp/timerId为NULL(errno=EINVAL)；sigev_notify为SIGEV_SIGNAL/SIGEV_NONE(errno=ENOTSUP)；sigev_notify无效(errno=EINVAL)；定时器资源不足(errno=EAGAIN)

timer_delete

函数声明

int timer_delete(timer_t)

头文件清单

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

功能说明

• 删除一个已创建的POSIX定时器
• 删除后定时器标识不再有效
• 若定时器正在运行则先停止再删除

前置条件

• 调用时序约束：需在timer_create成功创建定时器后调用
• 调用上下文约束：禁止在中断上下文调用

入参

名称	参数类型	详细说明	约束取值范围
timerId	timer_t	待删除的定时器标识	有效的timer_create返回的定时器标识

返回值

返回值	文字含义	触发场景
0	删除成功	定时器标识有效，删除成功
-1	删除失败	定时器标识无效，errno置为EINVAL

timer_getoverrun

函数声明

int timer_getoverrun(timer_t)

头文件清单

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

功能说明

• 获取指定定时器的超时溢出次数
• 超时溢出指定时器到期但上一次到期通知尚未处理完毕的情况
• 返回值不超过DELAYTIMER_MAX

前置条件

• 调用时序约束：需在timer_create成功创建定时器后调用
• 依赖关系：依赖定时器已通过timer_settime启动运行

入参

名称	参数类型	详细说明	约束取值范围
timerId	timer_t	待查询的定时器标识	有效的timer_create返回的定时器标识

返回值

返回值	文字含义	触发场景
非负整数	超时溢出次数	定时器标识有效，获取成功
-1	执行失败	定时器标识无效，errno置为EINVAL

timer_gettime

函数声明

int timer_gettime(timer_t, struct itimerspec *)

头文件清单

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

功能说明

• 获取指定定时器的剩余时间和间隔时间
• it_value成员为到下一次到期的剩余时间
• it_interval成员为定时器的周期间隔时间

前置条件

• 调用时序约束：需在timer_create成功创建定时器后调用

入参

名称	参数类型	详细说明	约束取值范围
timerId	timer_t	待查询的定时器标识	有效的timer_create返回的定时器标识

出参

名称	数据类型	输出说明
value	struct itimerspec *	写入定时器的剩余时间和周期间隔，需非NULL

返回值

返回值	文字含义	触发场景
0	执行成功	定时器标识有效，获取成功
-1	执行失败	定时器标识无效或value为NULL，errno置为EINVAL

timer_settime

函数声明

int timer_settime(timer_t, int, const struct itimerspec *__restrict, struct itimerspec *__restrict)

头文件清单

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

功能说明

• 设置或撤销定时器的到期时间和周期间隔
• it_value为0时表示停止定时器，定时器停止后仍需手动调用timer_delete删除
• it_interval为0时表示单次触发定时器
• 若oldValue非NULL，则返回之前的定时器设置

前置条件

• 调用时序约束：需在timer_create成功创建定时器后调用
• 调用上下文约束：禁止在中断上下文调用
• 依赖关系：it_value和it_interval中的时间值需为有效的timespec

入参

名称	参数类型	详细说明	约束取值范围
timerId	timer_t	待设置的定时器标识	有效的timer_create返回的定时器标识
flags	int	定时器模式标志	0（相对时间）或TIMER_ABSTIME(1)（绝对时间）
value	const struct itimerspec *__restrict	指向新定时器设置的结构体指针	非NULL，it_value和it_interval需为有效timespec

出参

名称	数据类型	输出说明
oldValue	struct itimerspec *__restrict	写入之前的定时器设置，可为NULL

返回值

返回值	文字含义	触发场景
0	设置成功	参数合法，设置成功
-1	设置失败	value为NULL或定时器标识无效或timespec参数无效，errno置为EINVAL

Structures

struct tm

struct tm {
    int tm_sec;
    int tm_min;
    int tm_hour;
    int tm_mday;
    int tm_mon;
    int tm_year;
    int tm_wday;
    int tm_yday;
    int tm_isdst;
    long __tm_gmtoff;
    const char *__tm_zone;
};

成员说明

成员名称	数据类型	描述
tm_sec	int	秒，取值范围0~59
tm_min	int	分，取值范围0~59
tm_hour	int	时，取值范围0~23
tm_mday	int	月内日期，取值范围1~31
tm_mon	int	月份，取值范围0~11（0表示一月）
tm_year	int	自1900年起的年数
tm_wday	int	星期几，取值范围0~6（0表示周日）
tm_yday	int	年内日期，取值范围0~365（0表示1月1日）
tm_isdst	int	夏令时标志，正数表示夏令时，0表示非夏令时，负数表示未知
__tm_gmtoff	long	时区偏移量，单位为秒
__tm_zone	const char *	时区名称

struct itimerspec

struct itimerspec {
    struct timespec it_interval;
    struct timespec it_value;
};

成员说明

成员名称	数据类型	描述
it_interval	struct timespec	定时器周期间隔，为0表示单次触发
it_value	struct timespec	首次到期时间，为0表示停止定时器

Macros

MAX_CLOCKS

#define MAX_CLOCKS 16

CLOCK_REALTIME

clock realtime clock_realtime

#define CLOCK_REALTIME 0

CLOCK_MONOTONIC

clock monotonic clock_monotonic

#define CLOCK_MONOTONIC 1

CLOCK_PROCESS_CPUTIME_ID

clock process cputime id clock_process_cputime_id process_cputime_id

#define CLOCK_PROCESS_CPUTIME_ID 2

CLOCK_THREAD_CPUTIME_ID

clock thread cputime id clock_thread_cputime_id thread_cputime_id

#define CLOCK_THREAD_CPUTIME_ID 3

CLOCK_MONOTONIC_RAW

clock monotonic raw clock_monotonic_raw monotonic_raw

#define CLOCK_MONOTONIC_RAW 4

CLOCK_REALTIME_COARSE

clock realtime coarse clock_realtime_coarse realtime_coarse

#define CLOCK_REALTIME_COARSE 5

CLOCK_MONOTONIC_COARSE

clock monotonic coarse clock_monotonic_coarse monotonic_coarse

#define CLOCK_MONOTONIC_COARSE 6

CLOCK_BOOTTIME

clock boottime clock_boottime

#define CLOCK_BOOTTIME 7

CLOCK_REALTIME_ALARM

clock realtime alarm clock_realtime_alarm realtime_alarm

#define CLOCK_REALTIME_ALARM 8

CLOCK_BOOTTIME_ALARM

boottime_alarm clock boottime alarm clock_boottime_alarm

#define CLOCK_BOOTTIME_ALARM 9

CLOCK_SGI_CYCLE

clock sgi cycle clock_sgi_cycle sgi_cycle

#define CLOCK_SGI_CYCLE 10

CLOCK_TAI

clock tai clock_tai

#define CLOCK_TAI 11

TIMER_ABSTIME

#define TIMER_ABSTIME 1

CLOCKS_PER_SEC

#define CLOCKS_PER_SEC 1000000L

TIME_UTC

#define TIME_UTC 1