Getting and changing time values (time_api.h)

Getting and changing time values (time_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/time/time_api.h from the KasperskyOS SDK.

Main capabilities of the API:

Get and modify the system time
Get the monotonic time that has elapsed since the moment the KasperskyOS kernel was started
Get the resolution of the sources of system and monotonic time
Receive RTC (Real Time Clock) characteristics

Information about API functions is provided in the table below.

time_api.h functions

Function	Information about the function
`KnGetSystemTimeRes()`	Purpose Gets the resolution of the system time source. Parameters [out] `res` – pointer to the structure containing the resolution of the system time source (in nanoseconds) in the `nsec` field. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnSetSystemTime()`	Purpose Sets the system time. Parameters [in] `time` – pointer to the structure containing the `sec` field, which indicates the number of seconds that have elapsed since January 1, 1970, and the `nsec` field, which indicates the number of nanoseconds that have elapsed since the time defined in the `sec` field. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information If the hardware platform contains an RTC, and the kernel has the required RTC driver, the kernel receives the system time from the RTC at startup. Otherwise, the countdown starts on January 1, 1970. In the second case, the actual system time to be set by the `KnSetSystemTime()` function can be obtained from the RTC driver running in user mode or from the network, for example.
`KnGetSystemTime()`	Purpose Gets the system time. Parameters [out] `time` – pointer to the structure containing the `sec` field, which indicates the number of seconds that have elapsed since January 1, 1970, and the `nsec` field, which indicates the number of nanoseconds that have elapsed since the time defined in the `sec` field. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnGetUpTimeRes()`	Purpose Gets the resolution of the source of monotonic time that has elapsed since the kernel startup. Parameters [out] `res` is the pointer to a structure whose `nsec` field contains the resolution of the monotonic time source, measured in nanoseconds since the kernel startup. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnGetUpTime()`	Purpose Gets the monotonic time that has elapsed since the kernel startup. Parameters [out] `time` – pointer to the structure containing the `sec` field, which indicates the number of seconds that have elapsed since the kernel startup, and the `nsec` field, which indicates the number of nanoseconds that have elapsed since the time defined in the `sec` field. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnGetRtcTime()`	Purpose Gets the system time. Parameters [out] `rt` – pointer to the structure containing the following time data: year, month, day, hours, minutes, seconds, and milliseconds. The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnGetMSecSinceStart()`	Purpose Gets the monotonic time that has elapsed since the kernel startup. Parameters N/A Returned values Monotonic time (in milliseconds) that has elapsed since the kernel startup.
`KnAdjSystemTime()`	Purpose Starts gradual adjustment of the system time. Parameters [in,optional] `adj` – pointer to the structure containing the amount of time by which the system time must be adjusted (sec10^9+nsec* nanoseconds), or `RTL_NULL` if you do not need to start an adjustment but instead only need information about a previously run adjustment (through the `prev` parameter). The type of structure is defined in the header file `sysroot--kos/include/rtl/rtc.h` from the KasperskyOS SDK. [in] `slew` – rate of system time adjustment (microseconds per second). [out] `prev` – pointer to the structure containing the amount of time correction that remained (or remains if `RTL_NULL` was indicated in the `adj` parameter) for the already running gradual adjustment to fully complete (sec10^9+nsec nanoseconds). The type of structure is defined in the header file `sysroot-*-kos/include/rtl/rtc.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information If a new adjustment is started before a previously running adjustment is finished, the previously running adjustment is interrupted.
`KnGetRtcInfo()`	Purpose Gets RTC characteristics. Parameters [out] `info` – pointer to a structure containing the RTC characteristics: resolution, and the lower and upper bounds of the countdown time (relative to January 1, 1970). Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. The function returns `rcUnimplemented` if the RTC is not available on the hardware platform, or if the required RTC driver is missing from the kernel.