gcc4mbed/external/mbed/rtc_time.h

   1 /* Title: time
   2  * Implementation of the C time.h functions
   3  *
   4  * Provides mechanisms to set and read the current time, based
   5  * on the microcontroller Real-Time Clock (RTC), plus some
   6  * standard C manipulation and formating functions.
   7  *
   8  * Example:
   9  * > #include "mbed.h"
  10  * >
  11  * > int main() {
  12  * >     set_time(1256729737);  // Set RTC time to Wed, 28 Oct 2009 11:35:37
  13  * >
  14  * >     while(1) {
  15  * >         time_t seconds = time(NULL);
  16  * >
  17  * >         printf("Time as seconds since January 1, 1970 = %d\n", seconds);
  18  * >
  19  * >         printf("Time as a basic string = %s", ctime(&seconds));
  20  * >
  21  * >         char buffer[32];
  22  * >         strftime(buffer, 32, "%I:%M %p\n", localtime(&seconds));
  23  * >         printf("Time as a custom formatted string = %s", buffer);
  24  * >
  25  * >         wait(1);
  26  * >     }
  27  * > }
  28  */
  29
  30 /* mbed Microcontroller Library - rtc_time
  31  * Copyright (c) 2009 ARM Limited. All rights reserved.
  32  */
  33
  34 #include <time.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #if 0 // for documentation only
  41 /* Function: time
  42  * Get the current time
  43  *
  44  * Returns the current timestamp as the number of seconds since January 1, 1970
  45  * (the UNIX timestamp). The value is based on the current value of the
  46  * microcontroller Real-Time Clock (RTC), which can be set using <set_time>.
  47  *
  48  * Example:
  49  * > #include "mbed.h"
  50  * >
  51  * > int main() {
  52  * >     time_t seconds = time(NULL);
  53  * >     printf("It is %d seconds since January 1, 1970\n", seconds);
  54  * > }
  55  *
  56  * Variables:
  57  *  t - Pointer to a time_t to be set, or NULL if not used
  58  *  returns - Number of seconds since January 1, 1970 (the UNIX timestamp)
  59  */
  60 time_t time(time_t *t);
  61 #endif
  62
  63 /* Function: set_time
  64  * Set the current time
  65  *
  66  * Initialises and sets the time of the microcontroller Real-Time Clock (RTC)
  67  * to the time represented by the number of seconds since January 1, 1970
  68  * (the UNIX timestamp).
  69  *
  70  * Example:
  71  * > #include "mbed.h"
  72  * >
  73  * > int main() {
  74  * >     set_time(1256729737); // Set time to Wed, 28 Oct 2009 11:35:37
  75  * > }
  76  *
  77  * Variables:
  78  *  t - Number of seconds since January 1, 1970 (the UNIX timestamp)
  79  */
  80 void set_time(time_t t);
  81
  82 #if 0 // for documentation only
  83 /* Function: mktime
  84  * Converts a tm structure in to a timestamp
  85  *
  86  * Converts the tm structure in to a timestamp in seconds since January 1, 1970
  87  * (the UNIX timestamp). The values of tm_wday and tm_yday of the tm structure
  88  * are also updated to their appropriate values.
  89  *
  90  * Example:
  91  * > #include "mbed.h"
  92  * >
  93  * > int main() {
  94  * >     // setup time structure for Wed, 28 Oct 2009 11:35:37
  95  * >     struct tm t;
  96  * >     t.tm_sec = 37;    // 0-59
  97  * >     t.tm_min = 35;    // 0-59
  98  * >     t.tm_hour = 11;   // 0-23
  99  * >     t.tm_mday = 28;   // 1-31
 100  * >     t.tm_mon = 9;     // 0-11
 101  * >     t.tm_year = 109;  // year since 1900
 102  * >
 103  * >     // convert to timestamp and display (1256729737)
 104  * >     time_t seconds = mktime(&t);
 105  * >     printf("Time as seconds since January 1, 1970 = %d\n", seconds);
 106  * > }
 107  *
 108  * Variables:
 109  *  t - The tm structure to convert
 110  *  returns - The converted timestamp
 111  */
 112 time_t mktime(struct tm *t);
 113 #endif
 114
 115 #if 0 // for documentation only
 116 /* Function: localtime
 117  * Converts a timestamp in to a tm structure
 118  *
 119  * Converts the timestamp pointed to by t to a (statically allocated)
 120  * tm structure.
 121  *
 122  * Example:
 123  * > #include "mbed.h"
 124  * >
 125  * > int main() {
 126  * >     time_t seconds = 1256729737;
 127  * >     struct tm *t = localtime(&seconds);
 128  * > }
 129  *
 130  * Variables:
 131  *  t - Pointer to the timestamp
 132  *  returns - Pointer to the (statically allocated) tm structure
 133  */
 134 struct tm *localtime(const time_t *t);
 135 #endif
 136
 137 #if 0 // for documentation only
 138 /* Function: ctime
 139  * Converts a timestamp to a human-readable string
 140  *
 141  * Converts a time_t timestamp in seconds since January 1, 1970 (the UNIX
 142  * timestamp) to a human readable string format. The result is of the
 143  * format: "Wed Oct 28 11:35:37 2009\n"
 144  *
 145  * Example:
 146  * > #include "mbed.h"
 147  * >
 148  * > int main() {
 149  * >     time_t seconds = time(NULL);
 150  * >     printf("Time as a string = %s", ctime(&seconds));
 151  * > }
 152  *
 153  * Variables:
 154  *  t - The timestamp to convert
 155  *  returns - Pointer to a (statically allocated) string containing the
 156  *            human readable representation, including a '\n' character
 157  */
 158 char *ctime(const time_t *t);
 159 #endif
 160
 161 #if 0 // for documentation only
 162 /* Function: strftime
 163  * Converts a tm structure to a custom format human-readable string
 164  *
 165  * Creates a formated string from a tm structure, based on a string format
 166  * specifier provided.
 167  *
 168  * Format Specifiers:
 169  *  %S - Second (00-59)
 170  *  %M - Minute (00-59)
 171  *  %H - Hour (00-23)
 172  *  %d - Day (01-31)
 173  *  %m - Month (01-12)
 174  *  %Y/%y - Year (2009/09)
 175  *
 176  *  %A/%a - Weekday Name (Monday/Mon)
 177  *  %B/%b - Month Name (January/Jan)
 178  *  %I - 12 Hour Format (01-12)
 179  *  %p - "AM" or "PM"
 180  *  %X - Time (14:55:02)
 181  *  %x - Date (08/23/01)
 182  *
 183  * Example:
 184  * > #include "mbed.h"
 185  * >
 186  * > int main() {
 187  * >     time_t seconds = time(NULL);
 188  * >
 189  * >     char buffer[32];
 190  * >     strftime(buffer, 32, "%I:%M %p\n", localtime(&seconds));
 191  * >     printf("Time as a formatted string = %s", buffer);
 192  * > }
 193  *
 194  * Variables:
 195  *  buffer - String buffer to store the result
 196  *  max - Maximum number of characters to store in the buffer
 197  *  format - Format specifier string
 198  *  t - Pointer to the tm structure to convert
 199  *  returns - Number of characters copied
 200  */
 201 size_t strftime(char *buffer, size_t max, const char *format, const struct tm *t);
 202 #endif
 203
 204 #ifdef __cplusplus
 205 }
 206 #endif