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