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 timebtp)

int 

Obtains the current time, accurate to milliseconds.

times (struct tmstm)

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 tmtm)

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 tmrestrict 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 tmtm)

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 tmrestrict 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 timespectspec1, struct timespectspec2)

int 

Pauses the current thread until a specified time arrives.

clock_getres (clockid_t id, struct timespectspec)

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 timespectspec)

int 

Sets the time for a clock.

clock_nanosleep (clockid_t id, int flag, const struct timespec tspec1, struct timespectspec2)

int 

Pauses the current thread until a specified time of a clock arrives.

timer_create (clockid_t id, struct sigeventrestrict 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 itimerspectspec)

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 tmtm)

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 (conststruct[tm]($api-api-SmartVision-Devices-tm.md)* tm)

Description:

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

Parameters:

Name

Description

tmIndicates 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 (conststruct[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

tmIndicates the pointer to the broken-down time in the tm structure.
bufIndicates 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

idIndicates the clock ID. Currently, the following values are supported: CLOCK_REALTIME, CLOCK_REALTIME_COARSE, CLOCK_MONOTONIC, CLOCK_MONOTONIC_COARSE, and CLOCK_MONOTONIC_RAW.
tspecIndicates 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

idIndicates the clock ID. Currently, the following values are supported: CLOCK_REALTIME, CLOCK_REALTIME_COARSE, CLOCK_MONOTONIC, CLOCK_MONOTONIC_COARSE, and CLOCK_MONOTONIC_RAW.
tspecIndicates 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,conststruct[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

idIndicates the clock ID. Only CLOCK_REALTIME is supported.
flagIndicates the clock type. This parameter must be set to 0
tspec1Indicates 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.
tspec2This 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,conststruct[timespec]($api-api-SmartVision-Devices-timespec.md)* tspec )

Description:

Sets the time for a clock.

Parameters:

Name

Description

idIndicates the clock ID. Only CLOCK_REALTIME is supported.
tspecIndicates 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 (consttime_t* timep)

Description:

Converts the date and time into a string.

Parameters:

Name

Description

timepIndicates 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 (consttime_t* t,char* buf )

Description:

Converts the date and time into a string. (This function is reentrant.)

Parameters:

Name

Description

tIndicates the pointer to the number of seconds to convert.
bufIndicates 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

time1Indicates the first time.
time2Indicates 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

tpIndicates 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 (constchar* buf)

Description:

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

Parameters:

Name

Description

bufIndicates 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 (consttime_t* t)

Description:

Converts the number of seconds to the UTC time in the tm structure.

Parameters:

Name

Description

tIndicates 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 (consttime_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

tIndicates the pointer to the number of seconds to convert.
tmIndicates 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 (consttime_t* t)

Description:

Converts the number of seconds to the local time in the tm structure.

Parameters:

Name

Description

tIndicates 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 (consttime_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

tIndicates the pointer to the number of seconds to convert.
tmIndicates 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

tmIndicates 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 (conststruct[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

tspec1Indicates 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.
tspec2This 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 (consttime_t* t)

Description:

Sets the system time.

Parameters:

Name

Description

tIndicates 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,constchar*restrict f,conststruct[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

sIndicates the pointer to the string.
nIndicates the size of the buffer for storing the string.
fIndicates the pointer to the required format.
tmIndicates 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,constchar*__restrict f,conststruct[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

sIndicates the pointer to the string.
nIndicates the size of the buffer for storing the string.
fIndicates the pointer to the required format.
tmIndicates the pointer to the broken-down time in the tm structure.
locIndicates 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 (constchar* s,constchar* 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

sIndicates the pointer to the string that contains only time data.
formatIndicates the pointer to the required format.
tmIndicates 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

tIndicates 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

tmIndicates 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

idIndicates the clock ID. Only CLOCK_REALTIME is supported.
evpIndicates the pointer to the asynchronous notification signal and action, which can be NULL.
tIndicates 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

tIndicates 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

tIndicates 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

tIndicates the ID of the timer to obtain.
tspecIndicates 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,conststruct[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

tIndicates the ID of the timer to set.
flagsIndicates the type of the timer to set. This parameter is not supported and must be set to 0.
valIndicates the pointer to the timer duration and interval to set.
oldIndicates 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

tmIndicates 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.