time

time 模块提供系统时间获取与设置、间隔定时器管理、文件时间戳修改等时间相关接口，基于 POSIX 标准的 sys/time.h 头文件实现。

头文件清单

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

接口清单

接口名称	功能简述
gettimeofday	获取当前时间，以秒和微秒的格式返回
getitimer	获取间隔定时器的当前值
setitimer	设置间隔定时器的值
utimes	修改文件的访问和修改时间
futimes	修改文件描述符对应文件的访问和修改时间
futimesat	相对于目录文件描述符修改文件的访问和修改时间
lutimes	修改符号链接文件的访问和修改时间
settimeofday	设置系统时间和时区信息
adjtime	微调系统时钟以同步校准

Functions

gettimeofday

int gettimeofday(struct timeval *__restrict, void *__restrict)

头文件清单

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

功能说明

获取当前系统时间，以秒和微秒的格式返回
通过struct timeval结构体返回自Epoch（1970-01-01 00:00:00 UTC）以来的时间
可选地通过timezone参数获取时区信息

出参

名称	数据类型	输出说明
tv	struct timeval *__restrict	返回自Epoch以来的当前时间，非NULL
tz	void *__restrict	返回时区信息，传NULL表示不获取时区

返回值

返回值	文字含义	触发场景
0	成功	成功获取时间
-1	失败	获取时间失败，errno被设置

getitimer

int getitimer(int, struct itimerval *)

头文件清单

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

功能说明

获取指定间隔定时器的当前值
返回定时器的间隔时间和剩余时间
支持三种定时器类型：ITIMER_REAL、ITIMER_VIRTUAL、ITIMER_PROF

入参

名称	参数类型	详细说明	约束取值范围
which	int	指定定时器类型	- ITIMER_REAL（0） - ITIMER_VIRTUAL（1） - ITIMER_PROF（2）

出参

名称	数据类型	输出说明
curr_value	struct itimerval *	返回定时器的间隔时间和剩余值

返回值

返回值	文字含义	触发场景
0	成功	成功获取定时器值
-1	失败	参数无效或获取失败，errno被设置

setitimer

int setitimer(int, const struct itimerval *__restrict, struct itimerval *__restrict)

头文件清单

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

功能说明

设置指定间隔定时器的值
可同时获取定时器的旧值
定时器到期后根据it_interval自动重新加载

入参

名称	参数类型	详细说明	约束取值范围
which	int	指定定时器类型	- ITIMER_REAL（0） - ITIMER_VIRTUAL（1） - ITIMER_PROF（2）
new_value	const struct itimerval *__restrict	指向新定时器值的结构体指针	非NULL

出参

名称	数据类型	输出说明
old_value	struct itimerval *__restrict	返回定时器的旧值，传NULL表示不获取旧值

返回值

返回值	文字含义	触发场景
0	成功	成功设置定时器值
-1	失败	参数无效或设置失败，errno被设置

utimes

int utimes(const char *, const struct timeval[2])

头文件清单

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

功能说明

修改指定文件的访问时间和修改时间
时间精度为微秒级别
通过路径名指定文件

入参

名称	参数类型	详细说明	约束取值范围
filename	const char *	文件路径名	非NULL，有效的文件路径
times	const struct timeval[2]	时间数组，times[0]为访问时间，times[1]为修改时间	NULL或包含两个timeval结构体的数组

返回值

返回值	文字含义	触发场景
0	成功	成功修改文件时间
-1	失败	文件不存在或权限不足，errno被设置

futimes

int futimes(int, const struct timeval[2])

头文件清单

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

功能说明

修改由文件描述符指定的文件的访问时间和修改时间
时间精度为微秒级别
通过文件描述符而非路径名指定文件

入参

名称	参数类型	详细说明	约束取值范围
fd	int	文件描述符	有效的已打开文件描述符
times	const struct timeval[2]	时间数组，times[0]为访问时间，times[1]为修改时间	NULL或包含两个timeval结构体的数组

返回值

返回值	文字含义	触发场景
0	成功	成功修改文件时间
-1	失败	文件描述符无效或权限不足，errno被设置

futimesat

int futimesat(int, const char *, const struct timeval[2])

头文件清单

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

功能说明

相对于目录文件描述符修改文件的访问时间和修改时间
时间精度为微秒级别
支持相对路径和绝对路径

入参

名称	参数类型	详细说明	约束取值范围
dirfd	int	目录文件描述符	AT_FDCWD或有效的目录文件描述符
pathname	const char *	文件路径名，相对于dirfd	非NULL，有效路径
times	const struct timeval[2]	时间数组，times[0]为访问时间，times[1]为修改时间	NULL或包含两个timeval结构体的数组

返回值

返回值	文字含义	触发场景
0	成功	成功修改文件时间
-1	失败	路径无效或权限不足，errno被设置

lutimes

int lutimes(const char *, const struct timeval[2])

头文件清单

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

功能说明

修改符号链接文件自身的访问时间和修改时间，不跟随符号链接
时间精度为微秒级别
与utimes的区别在于不解引用符号链接

入参

名称	参数类型	详细说明	约束取值范围
filename	const char *	符号链接文件路径名	非NULL，有效的符号链接路径
times	const struct timeval[2]	时间数组，times[0]为访问时间，times[1]为修改时间	NULL或包含两个timeval结构体的数组

返回值

返回值	文字含义	触发场景
0	成功	成功修改符号链接时间
-1	失败	路径无效或权限不足，errno被设置

settimeofday

int settimeofday(const struct timeval *, const struct timezone *)

头文件清单

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

功能说明

设置系统时间和时区信息
可同时设置时间和时区，也可仅设置其中一项
tv_usec取值范围为0到999999，tv_sec不可为负数

前置条件

调用者需具备设置系统时间的权限
tv和tz参数不可同时为NULL

入参

名称	参数类型	详细说明	约束取值范围
tv	const struct timeval *	指向待设置时间的timeval结构体指针	NULL或有效的timeval指针；tv_usec范围：0 ~ 999999；tv_sec不可为负数
tz	const struct timezone *	指向待设置时区信息的timezone结构体指针	NULL或有效的timezone指针；tz_minuteswest范围：-720 ~ 840

返回值

返回值	文字含义	触发场景
0	成功	成功设置系统时间或时区
-1	失败	参数无效或设置失败，errno被设置

adjtime

int adjtime(const struct timeval *, struct timeval *)

头文件清单

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

功能说明

微调系统时钟以逐渐同步校准
通过指定增量值对系统时间进行小幅调整，而非一次性设置
可获取上一次调整的剩余时间

入参

名称	参数类型	详细说明	约束取值范围
delta	const struct timeval *	指向时间调整量的timeval结构体指针	NULL或有效的timeval指针；tv_usec范围：-1000000 ~ 1000000

出参

名称	数据类型	输出说明
oldDelta	struct timeval *	返回上次调整的剩余时间

返回值

返回值	文字含义	触发场景
0	成功	成功设置时间调整量
-1	失败	参数无效，errno被设置

Structures

itimerval

struct itimerval {
    struct timeval it_interval;
    struct timeval it_value;
};

成员说明

成员名称	数据类型	描述
it_interval	struct timeval	定时器间隔时间，定时器到期后自动重新加载的值
it_value	struct timeval	定时器当前剩余时间，定时器到期前的倒计时值

timezone

struct timezone {
    int tz_minuteswest;
    int tz_dsttime;
};

成员说明

成员名称	数据类型	描述
tz_minuteswest	int	格林威治以西的分钟数，正值表示西时区
tz_dsttime	int	夏令时校正类型

Macros

ITIMER_REAL

#define ITIMER_REAL 0

ITIMER_VIRTUAL

#define ITIMER_VIRTUAL 1

ITIMER_PROF

#define ITIMER_PROF 2