## **Overview**
Provides time-related structures and functions.
**Since:**
1.0
**Version:**
1.0
## **Summary**
## Files
Provides structures and functions related to the curren time. | |
Provides structures and functions related to the process time. | |
Provides time-related structures and functions. |
## Data Structures
Describes the time, accurate to millisecond. | |
Describes CPU time of a process and its child processes. | |
Describes date and time information. | |
## Macros
Defines the clock that runs in real time. |
## Functions
Obtains the current time, accurate to milliseconds. | |
Obtains the number of clock ticks of the current process. | |
time (time_t *t) | |
difftime (time_t time1, time_t time2) | Calculates the difference between two times, in seconds. |
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) | 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. |
Converts the broken-down time in the tm structure into a string. | |
ctime (const time_t *timep) | 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) | 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) | Converts the broken-down time in the tm structure into a string. (This function is reentrant.) |
ctime_r (const time_t *t, char *buf) | Converts the date and time into a string. (This function is reentrant.) |
nanosleep (const struct timespec *tspec1, struct timespec *tspec2) | Pauses the current thread until a specified time arrives. |
clock_getres (clockid_t id, struct timespec *tspec) | Obtains the precision of a clock. |
clock_gettime (clockid_t id, struct timespec *tspec) | |
clock_settime (clockid_t id, const struct timespec *tspec) | |
clock_nanosleep (clockid_t id, int flag, const struct timespec *tspec1, struct timespec *tspec2) | 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) | Creates a timer for the process. |
timer_delete (timer_t t) | Deletes a timer for the process. |
timer_settime (timer_t t, int flags, const struct itimerspec *__restrict val, struct itimerspec *__restrict old) | |
timer_gettime (timer_t t, struct itimerspec *tspec) | Obtains a timer of the process. |
timer_getoverrun (timer_t t) | Obtains the number of times that a timer overruns. |
strptime (const char *s, const char *format, struct tm *tm) | 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) | |
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:**
| 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:**
| 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:**
**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:**
**Returns:**
Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.
## 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:**
**Returns:**
Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.
## clock\_settime\(\)
```
int clock_settime (clockid_t id, const struct [timespec](timespec.md) * tspec )
```
**Description:**
Sets the time for a clock.
**Parameters:**
| 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.
## ctime\(\)
```
char* ctime (const time_t * timep)
```
**Description:**
Converts the date and time into a string.
**Parameters:**
| 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:**
| 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:**
| 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:**
| 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:**
| 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:**
| 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.
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:**
| t | Indicates the pointer to the number of seconds to convert. |
| tm | Indicates the pointer to the tm structure. |
**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.
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:**
| 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.
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:**
| t | Indicates the pointer to the number of seconds to convert. |
| tm | Indicates the pointer to the tm structure. |
**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.
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:**
| 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.
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:**
| 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.
## stime\(\)
```
int stime (const time_t * t)
```
**Description:**
Sets the system time.
**Parameters:**
| 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.
## 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:**
| 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:**
| 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:**
| 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:**
| 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:**
| 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.
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:**
| 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.
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:**
| 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.
## timer\_getoverrun\(\)
```
int timer_getoverrun (timer_t t)
```
**Description:**
Obtains the number of times that a timer overruns.
**Parameters:**
| 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.
## timer\_gettime\(\)
```
int timer_gettime (timer_t t, struct [itimerspec](itimerspec.md) * tspec )
```
**Description:**
Obtains a timer of the process.
**Parameters:**
| 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.
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:**
**Returns:**
Returns **0** if the operation is successful; returns **-1** and sets **errno** to a value in the following table if the operation fails.
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:**
| 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.