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

  1. #define CLOCK_REALTIME 0

Description:

Defines the clock that runs in real time.

Function Documentation

asctime()

  1. char* asctime (const struct [tm]($api-api-SmartVision-Devices-tm.md) * tm)

Description:

Converts the broken-down time in the tm 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()

  1. char* asctime_r (const struct [tm]($api-api-SmartVision-Devices-tm.md) *__restrict tm, char *__restrict buf )

Description:

Converts the broken-down time in the tm 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()

  1. int clock_getres (clockid_t id, struct [timespec]($api-api-SmartVision-Devices-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()

  1. int clock_gettime (clockid_t id, struct [timespec]($api-api-SmartVision-Devices-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()

  1. int clock_nanosleep (clockid_t id, int flag, const struct [timespec]($api-api-SmartVision-Devices-timespec.md) * tspec1, struct [timespec]($api-api-SmartVision-Devices-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()

  1. int clock_settime (clockid_t id, const struct [timespec]($api-api-SmartVision-Devices-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()

  1. 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()

  1. 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()

  1. 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()

  1. int ftime (struct [timeb]($api-api-SmartVision-Devices-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()

  1. struct [tm]($api-api-SmartVision-Devices-tm.md)* getdate (const char * buf)

Description:

Converts a time string to the broken-down time in the tm 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 structure if the operation is successful; returns NULL otherwise.

gmtime()

  1. struct [tm]($api-api-SmartVision-Devices-tm.md)* gmtime (const time_t * t)

Description:

Converts the number of seconds to the UTC time in the tm 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 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()

  1. struct [tm]($api-api-SmartVision-Devices-tm.md)* gmtime_r (const time_t *__restrict t, struct [tm]($api-api-SmartVision-Devices-tm.md) *__restrict tm )

Description:

Converts the number of seconds to the UTC time in the tm 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.

Returns:

Returns the pointer to the UTC time in the tm 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()

  1. struct [tm]($api-api-SmartVision-Devices-tm.md)* localtime (const time_t * t)

Description:

Converts the number of seconds to the local time in the tm 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 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()

  1. struct [tm]($api-api-SmartVision-Devices-tm.md)* localtime_r (const time_t *__restrict t, struct [tm]($api-api-SmartVision-Devices-tm.md) *__restrict tm )

Description:

Converts the number of seconds to the local time in the tm 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.

Returns:

Returns the pointer to the local time in the tm 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.

mktime()

  1. time_t mktime (struct [tm]($api-api-SmartVision-Devices-tm.md) * tm)

Description:

Converts the broken-down time in the tm 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()

  1. int nanosleep (const struct [timespec]($api-api-SmartVision-Devices-timespec.md) * tspec1, struct [timespec]($api-api-SmartVision-Devices-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()

  1. 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()

  1. size_t strftime (char *restrict s, size_t n, const char *restrict f, const struct [tm]($api-api-SmartVision-Devices-tm.md) *restrict tm )

Description:

Converts the broken-down time in the tm 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()

  1. size_t strftime_l (char *__restrict s, size_t n, const char *__restrict f, const struct [tm]($api-api-SmartVision-Devices-tm.md) *__restrict tm, locale_t loc )

Description:

Converts the broken-down time in the tm 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()

  1. char* strptime (const char * s, const char * format, struct [tm]($api-api-SmartVision-Devices-tm.md) * tm )

Description:

Converts a time string to the broken-down time in the tm structure.

This function parses the input string s based on format and stores the result in the tm 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()

  1. 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()

  1. time_t timegm (struct [tm]($api-api-SmartVision-Devices-tm.md) * tm)

Description:

Converts the broken-down time in the tm 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()

  1. int timer_create (clockid_t id, struct [sigevent]($api-api-SmartVision-Devices-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()

  1. 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()

  1. 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()

  1. int timer_gettime (timer_t t, struct [itimerspec]($api-api-SmartVision-Devices-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()

  1. int timer_settime (timer_t t, int flags, const struct [itimerspec]($api-api-SmartVision-Devices-itimerspec.md) *__restrict val, struct [itimerspec]($api-api-SmartVision-Devices-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()

  1. clock_t times (struct [tms]($api-api-SmartVision-Devices-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.