mbed_rtc_time.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef __MBED_RTC_TIME_H__
00019 #define __MBED_RTC_TIME_H__
00020 
00021 #include <time.h>
00022 
00023 #ifdef __cplusplus
00024 extern "C" {
00025 #endif
00026 
00027 /** \addtogroup platform-public-api */
00028 /** @{*/
00029 
00030 /**
00031  * \defgroup platform_rtc_time rtc_time functions
00032  * @{
00033  */
00034 
00035 /* Timeval definition for non GCC_ARM toolchains */
00036 #if !defined(__GNUC__) || defined(__CC_ARM) || defined(__clang__)
00037 struct timeval {
00038     time_t tv_sec;
00039     int32_t tv_usec;
00040 };
00041 #endif
00042 
00043 /** Implementation of the C time.h functions
00044  *
00045  * Provides mechanisms to set and read the current time, based
00046  * on the microcontroller Real-Time Clock (RTC), plus some
00047  * standard C manipulation and formatting functions.
00048  *
00049  * Example:
00050  * @code
00051  * #include "mbed.h"
00052  *
00053  * int main() {
00054  *     set_time(1256729737);  // Set RTC time to Wed, 28 Oct 2009 11:35:37
00055  *
00056  *     while (true) {
00057  *         time_t seconds = time(NULL);
00058  *
00059  *         printf("Time as seconds since January 1, 1970 = %u\n", (unsigned int)seconds);
00060  *
00061  *         printf("Time as a basic string = %s", ctime(&seconds));
00062  *
00063  *         char buffer[32];
00064  *         strftime(buffer, 32, "%I:%M %p\n", localtime(&seconds));
00065  *         printf("Time as a custom formatted string = %s", buffer);
00066  *
00067  *         wait(1);
00068  *     }
00069  * }
00070  * @endcode
00071  */
00072 
00073 /** Set the current time
00074  *
00075  * Initializes and sets the time of the microcontroller Real-Time Clock (RTC)
00076  * to the time represented by the number of seconds since January 1, 1970
00077  * (the UNIX timestamp).
00078  *
00079  * @param t Number of seconds since January 1, 1970 (the UNIX timestamp)
00080  *
00081  * @note Synchronization level: Thread safe
00082  *
00083  * Example:
00084  * @code
00085  * #include "mbed.h"
00086  *
00087  * int main() {
00088  *     set_time(1256729737); // Set time to Wed, 28 Oct 2009 11:35:37
00089  * }
00090  * @endcode
00091  */
00092 void set_time(time_t t);
00093 
00094 /** Attach an external RTC to be used for the C time functions
00095  *
00096  * @note Synchronization level: Thread safe
00097  *
00098  * @param read_rtc pointer to function which returns current UNIX timestamp
00099  * @param write_rtc pointer to function which sets current UNIX timestamp, can be NULL
00100  * @param init_rtc pointer to function which initializes RTC, can be NULL
00101  * @param isenabled_rtc pointer to function which returns if the RTC is enabled, can be NULL
00102  */
00103 void attach_rtc(time_t (*read_rtc)(void), void (*write_rtc)(time_t), void (*init_rtc)(void), int (*isenabled_rtc)(void));
00104 
00105 /** Standard lib retarget, get time since Epoch
00106  *
00107  * @param tv    Structure containing time_t seconds and useconds_t microseconds. Due to
00108  *              separate target specific RTC implementations only the seconds component is used.
00109  * @param tz    DEPRECATED IN THE STANDARD: This parameter is left in for legacy code. It is
00110  *              not used.
00111  * @return      0 on success, -1 on a failure.
00112  * @note Synchronization level: Thread safe
00113  *
00114  */
00115 int gettimeofday(struct timeval *tv, void *tz);
00116 
00117 /** Standard lib retarget, set time since Epoch
00118  *
00119  * @param tv    Structure containing time_t seconds and useconds_t microseconds. Due to
00120  *              separate target specific RTC implementations only the seconds component is used.
00121  * @param tz    DEPRECATED IN THE STANDARD: This parameter is left in for legacy code. It is
00122  *              not used.
00123  * @return      Time in seconds on success, -1 on a failure.
00124  * @note Synchronization level: Thread safe
00125  *
00126  */
00127 int settimeofday(const struct timeval *tv, const struct timezone *tz);
00128 
00129 #ifdef __cplusplus
00130 }
00131 #endif
00132 
00133 /** @}*/
00134 /** @}*/
00135 
00136 #endif /* __MBED_RTC_TIME_H__ */