# TIME ## **Overview** Provides time-related structures and functions. **Since:** 1.0 **Version:** 1.0 ## **Summary** ## Files

File Name	Description
timeb.h	Provides structures and functions related to the curren time.
times.h	Provides structures and functions related to the process time.
time.h	Provides time-related structures and functions.

## Data Structures

Data Structure Name	Description
timeb	Describes the time, accurate to millisecond.
tms	Describes CPU time of a process and its child processes.
tm	Describes date and time information.
itimerspec	Sets a timer.

## Macros

Macro Name and Value	Description
CLOCK_REALTIME 0	Defines the clock that runs in real time.

## Functions

Function Name	Description
ftime (struct timeb *tp)	int Obtains the current time, accurate to milliseconds.
times (struct tms *tm)	clock_t Obtains the number of clock ticks of the current process.
time (time_t *t)	time_t Obtains the time.
difftime (time_t time1, time_t time2)	double Calculates the difference between two times, in seconds.
mktime (struct tm *tm)	time_t Converts the broken-down time in the tm structure into seconds.
strftime (char restrict s, size_t n, const char restrict f, const struct tm *restrict tm)	size_t Converts the broken-down time in the tm structure to a string in the required format.
gmtime (const time_t *t)	struct tm * Converts the number of seconds to the UTC time in the tm structure.
localtime (const time_t *t)	struct tm * Converts the number of seconds to the local time in the tm structure.
asctime (const struct tm *tm)	char * Converts the broken-down time in the tm structure into a string.
ctime (const time_t *timep)	char * Converts the date and time into a string.
strftime_l (char __restrict s, size_t n, const char __restrict f, const struct tm *__restrict tm, locale_t loc)	size_t Converts the broken-down time in the tm structure to a string in a specified programming language and format.
gmtime_r (const time_t __restrict t, struct tm __restrict tm)	struct tm * Converts the number of seconds to the UTC time in the tm structure. (This function is reentrant.)
localtime_r (const time_t __restrict t, struct tm __restrict tm)	struct tm * Converts the number of seconds to the local time in the tm structure. (This function is reentrant.)
asctime_r (const struct tm __restrict tm, char __restrict buf)	char * Converts the broken-down time in the tm structure into a string. (This function is reentrant.)
ctime_r (const time_t t, char buf)	char * Converts the date and time into a string. (This function is reentrant.)
nanosleep (const struct timespec tspec1, struct timespec tspec2)	int Pauses the current thread until a specified time arrives.
clock_getres (clockid_t id, struct timespec *tspec)	int Obtains the precision of a clock.
clock_gettime (clockid_t id, struct timespec *tspec)	int Obtains the time of a clock.
clock_settime (clockid_t id, const struct timespec *tspec)	int Sets the time for a clock.
clock_nanosleep (clockid_t id, int flag, const struct timespec tspec1, struct timespec tspec2)	int Pauses the current thread until a specified time of a clock arrives.
timer_create (clockid_t id, struct sigevent __restrict evp, timer_t __restrict t)	int Creates a timer for the process.
timer_delete (timer_t t)	int Deletes a timer for the process.
timer_settime (timer_t t, int flags, const struct itimerspec __restrict val, struct itimerspec __restrict old)	int Sets a timer for the process.
timer_gettime (timer_t t, struct itimerspec *tspec)	int Obtains a timer of the process.
timer_getoverrun (timer_t t)	int Obtains the number of times that a timer overruns.
strptime (const char s, const char format, struct tm *tm)	char * Converts a time string to the broken-down time in the tm structure.
getdate (const char *buf)	struct tm * Converts a time string to the broken-down time in the tm structure.
stime (const time_t *t)	int Sets the system time.
timegm (struct tm *tm)	time_t Converts the broken-down time in the tm structure to the number of seconds.

## **Details** ## **Macro Definition Documentation** ## CLOCK\_REALTIME ``` #define CLOCK_REALTIME 0 ``` **Description:** Defines the clock that runs in real time. ## **Function Documentation** ## asctime\(\) ``` char* asctime (const struct [tm](tm.md) * tm) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure into a string. **Parameters:**

Name	Description
tm	Indicates the pointer to the broken-down time in the tm structure.

**Returns:** Returns the string in the format of **week month day hour:minute:second year**, for example, **Thu Jan 1 08:00:00 1970**. If the conversion fails, the program ends. ## asctime\_r\(\) ``` char* asctime_r (const struct [tm](tm.md) *__restrict tm, char *__restrict buf ) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure into a string. \(This function is reentrant.\) **Parameters:**

Name	Description
tm	Indicates the pointer to the broken-down time in the tm structure.
buf	Indicates the pointer to the buffer for storing the string.

**Returns:** Returns the string in the format of **week month day hour:minute:second year**, for example, **Thu Jan 1 08:00:00 1970**. If the conversion fails, the program ends. ## clock\_getres\(\) ``` int clock_getres (clockid_t id, struct [timespec](timespec.md) * tspec ) ``` **Description:** Obtains the precision of a clock. **Parameters:**

Name	Description
id	Indicates the clock ID. Currently, the following values are supported: CLOCK_REALTIME, CLOCK_REALTIME_COARSE, CLOCK_MONOTONIC, CLOCK_MONOTONIC_COARSE, and CLOCK_MONOTONIC_RAW.
tspec	Indicates the pointer to the data obtained.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## clock\_gettime\(\) ``` int clock_gettime (clockid_t id, struct [timespec](timespec.md) * tspec ) ``` **Description:** Obtains the time of a clock. **Parameters:**

Name	Description
id	Indicates the clock ID. Currently, the following values are supported: CLOCK_REALTIME, CLOCK_REALTIME_COARSE, CLOCK_MONOTONIC, CLOCK_MONOTONIC_COARSE, and CLOCK_MONOTONIC_RAW.
tspec	Indicates the pointer to the time obtained.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## clock\_nanosleep\(\) ``` int clock_nanosleep (clockid_t id, int flag, const struct [timespec](timespec.md) * tspec1, struct [timespec](timespec.md) * tspec2 ) ``` **Description:** Pauses the current thread until a specified time of a clock arrives. A sleeping thread cannot be woken up by a signal. **Parameters:**

Name	Description
id	Indicates the clock ID. Only CLOCK_REALTIME is supported.
flag	Indicates the clock type. This parameter must be set to 0
tspec1	Indicates the pointer to the minimum duration that the current thread is paused. Currently, the unit of precision is tick, and the discrepancy is fewer than 2 ticks.
tspec2	This parameter is not used yet.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## clock\_settime\(\) ``` int clock_settime (clockid_t id, const struct [timespec](timespec.md) * tspec ) ``` **Description:** Sets the time for a clock. **Parameters:**

Name	Description
id	Indicates the clock ID. Only CLOCK_REALTIME is supported.
tspec	Indicates the pointer to the time to set.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## ctime\(\) ``` char* ctime (const time_t * timep) ``` **Description:** Converts the date and time into a string. **Parameters:**

Name	Description
timep	Indicates the number of seconds to convert.

**Returns:** Returns the string in the format of **week month day hour:minute:second year**, for example, **Thu Jan 1 08:00:00 1970**. If the conversion fails, the program ends. ## ctime\_r\(\) ``` char* ctime_r (const time_t * t, char * buf ) ``` **Description:** Converts the date and time into a string. \(This function is reentrant.\) **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to convert.
buf	Indicates the pointer to the buffer for storing the string.

**Returns:** Returns the string in the format of **week month day hour:minute:second year**, for example, **Thu Jan 1 08:00:00 1970**. If the conversion fails, the program ends. ## difftime\(\) ``` double difftime (time_t time1, time_t time2 ) ``` **Description:** Calculates the difference between two times, in seconds. **Parameters:**

Name	Description
time1	Indicates the first time.
time2	Indicates the second time.

**Returns:** Returns the difference, represented using a double. ## ftime\(\) ``` int ftime (struct [timeb](timeb.md) * tp) ``` **Description:** Obtains the current time, accurate to milliseconds. The time obtained is the total number of milliseconds elapsed since January 1, 1970 00:00:00 \(UTC\). **Parameters:**

Name	Description
tp	Indicates the pointer to the number of milliseconds. timezone and dstflag are set to 0.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## getdate\(\) ``` struct [tm](tm.md)* getdate (const char * buf) ``` **Description:** Converts a time string to the broken-down time in the [tm](tm.md) structure. **Parameters:**

Name	Description
buf	Indicates the pointer to the time string. The format is specified by the file defined by the environment variable DATEMSK.

**Returns:** Returns the time in the [tm](tm.md) structure if the operation is successful; returns **NULL** otherwise. ## gmtime\(\) ``` struct [tm](tm.md)* gmtime (const time_t * t) ``` **Description:** Converts the number of seconds to the UTC time in the [tm](tm.md) structure. **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to convert.

**Returns:** Returns the pointer to the UTC time in the [tm](tm.md) structure if the conversion is successful; returns **NULL** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EOVERFLOW	Inappropriate input parameter.

## gmtime\_r\(\) ``` struct [tm](tm.md)* gmtime_r (const time_t *__restrict t, struct [tm](tm.md) *__restrict tm ) ``` **Description:** Converts the number of seconds to the UTC time in the [tm](tm.md) structure. \(This function is reentrant.\) This function is used in the multi-task environment. **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to convert.
tm	Indicates the pointer to the tm structure.

errno	Description
EOVERFLOW	Inappropriate input parameter.

## localtime\(\) ``` struct [tm](tm.md)* localtime (const time_t * t) ``` **Description:** Converts the number of seconds to the local time in the [tm](tm.md) structure. **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to convert.

**Returns:** Returns the pointer to the local time in the [tm](tm.md) structure if the conversion is successful; returns **NULL** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EOVERFLOW	Inappropriate input parameter.

## localtime\_r\(\) ``` struct [tm](tm.md)* localtime_r (const time_t *__restrict t, struct [tm](tm.md) *__restrict tm ) ``` **Description:** Converts the number of seconds to the local time in the [tm](tm.md) structure. \(This function is reentrant.\) **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to convert.
tm	Indicates the pointer to the tm structure.

errno	Description
EOVERFLOW	Inappropriate input parameter.

## mktime\(\) ``` time_t mktime (struct [tm](tm.md) * tm) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure into seconds. **Parameters:**

Name	Description
tm	Indicates the pointer to the broken-down time in the tm structure.

**Returns:** Returns the total number of seconds elapsed since January 1, 1970 00:00:00 \(UTC\) if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EOVERFLOW	Inappropriate input parameter.

## nanosleep\(\) ``` int nanosleep (const struct [timespec](timespec.md) * tspec1, struct [timespec](timespec.md) * tspec2 ) ``` **Description:** Pauses the current thread until a specified time arrives. A sleeping thread cannot be woken up by a signal. **Parameters:**

Name	Description
tspec1	Indicates the pointer to the minimum duration that the current thread is paused. Currently, the unit of precision is tick, and the discrepancy is fewer than 2 ticks.
tspec2	This parameter is not used yet.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## stime\(\) ``` int stime (const time_t * t) ``` **Description:** Sets the system time. **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds to set.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## strftime\(\) ``` size_t strftime (char *restrict s, size_t n, const char *restrict f, const struct [tm](tm.md) *restrict tm ) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure to a string in the required format. **Parameters:**

Name	Description
s	Indicates the pointer to the string.
n	Indicates the size of the buffer for storing the string.
f	Indicates the pointer to the required format.
tm	Indicates the pointer to the broken-down time in the tm structure.

**Returns:** Returns the number of bytes in the string if the conversion is successful; returns **0** otherwise. ## strftime\_l\(\) ``` size_t strftime_l (char *__restrict s, size_t n, const char *__restrict f, const struct [tm](tm.md) *__restrict tm, locale_t loc ) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure to a string in a specified programming language and format. **Parameters:**

Name	Description
s	Indicates the pointer to the string.
n	Indicates the size of the buffer for storing the string.
f	Indicates the pointer to the required format.
tm	Indicates the pointer to the broken-down time in the tm structure.
loc	Indicates the required programming language. Currently, only C programming language is supported.

**Returns:** Returns the number of bytes in the string if the conversion is successful; returns **0** otherwise. ## strptime\(\) ``` char* strptime (const char * s, const char * format, struct [tm](tm.md) * tm ) ``` **Description:** Converts a time string to the broken-down time in the [tm](tm.md) structure. This function parses the input string **s** based on **format** and stores the result in the [tm](tm.md) structure. **Parameters:**

Name	Description
s	Indicates the pointer to the string that contains only time data.
format	Indicates the pointer to the required format.
tm	Indicates the pointer to the tm structure.

**Returns:** Returns the pointer to the position to which the string has been processed \(the next character to be processed\) upon the conversion completion if the operation is successful; returns **NULL** otherwise. ## time\(\) ``` time_t time (time_t * t) ``` **Description:** Obtains the time. The time obtained is the total number of seconds elapsed since January 1, 1970 00:00:00 \(UTC\). **Parameters:**

Name	Description
t	Indicates the pointer to the number of seconds. You can also pass NULL to use the return value.

**Returns:** Returns the number of seconds. ## timegm\(\) ``` time_t timegm (struct [tm](tm.md) * tm) ``` **Description:** Converts the broken-down time in the [tm](tm.md) structure to the number of seconds. **Parameters:**

Name	Description
tm	Indicates the pointer to the broken-down time in the tm structure to convert.

**Returns:** Returns the number of seconds if the operation is successful; returns **NULL** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EOVERFLOW	The input parameter is too long.

## timer\_create\(\) ``` int timer_create (clockid_t id, struct [sigevent](sigevent.md) *__restrict evp, timer_t *__restrict t ) ``` **Description:** Creates a timer for the process. **Parameters:**

Name	Description
id	Indicates the clock ID. Only CLOCK_REALTIME is supported.
evp	Indicates the pointer to the asynchronous notification signal and action, which can be NULL.
t	Indicates the pointer to the timer ID.

**Attention:** **sigev\_notify** in the **sigevent** structure must be **SIGEV\_SIGNAL**. **Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.
ENOTSUP	The value of evp is not NULL and sigev_notify is not SIGEV_SIGNAL.

## timer\_delete\(\) ``` int timer_delete (timer_t t) ``` **Description:** Deletes a timer for the process. **Parameters:**

Name	Description
t	Indicates the ID of the timer to delete.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## timer\_getoverrun\(\) ``` int timer_getoverrun (timer_t t) ``` **Description:** Obtains the number of times that a timer overruns. **Parameters:**

Name	Description
t	Indicates the ID of the timer to obtain.

**Returns:** Returns the number of times if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Invalid input.

## timer\_gettime\(\) ``` int timer_gettime (timer_t t, struct [itimerspec](itimerspec.md) * tspec ) ``` **Description:** Obtains a timer of the process. **Parameters:**

Name	Description
t	Indicates the ID of the timer to obtain.
tspec	Indicates the pointer to the timer duration and interval.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
EINVAL	Incorrect parameter or timer operation failure.

## timer\_settime\(\) ``` int timer_settime (timer_t t, int flags, const struct [itimerspec](itimerspec.md) *__restrict val, struct [itimerspec](itimerspec.md) *__restrict old ) ``` **Description:** Sets a timer for the process. **Parameters:**

Name	Description
t	Indicates the ID of the timer to set.
flags	Indicates the type of the timer to set. This parameter is not supported and must be set to 0.
val	Indicates the pointer to the timer duration and interval to set.
old	Indicates the pointer to the timer duration and interval before the current setting.

**Returns:** Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.

errno	Description
ENOSYS	The value of flags is not 0.
EINVAL	Incorrect parameter or timer operation failure.

## times\(\) ``` clock_t times (struct [tms](tms.md) * tm) ``` **Description:** Obtains the number of clock ticks of the current process. **Parameters:**

Name	Description
tm	Indicates the pointer to the tms structure that contains the clock ticks, which can be NULL.

**Returns:** Returns the number of clock ticks of CPU 0.