lib/silcutil/silctime.h

   1 /*
   2
   3   silctime.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/Time Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface provides various utility functions for getting current
  25  * time and converting different time representations into the SilcTime
  26  * representation.
  27  *
  28  ***/
  29
  30 #ifndef SILCTIME_H
  31 #define SILCTIME_H
  32
  33 /****s* silcutil/SilcTime
  34  *
  35  * NAME
  36  *
  37  *    typedef struct { ... } *SilcTime, SilcTimeStruct;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context represents time value.  It includes date and time
  42  *    down to millisecond precision.  The structure size is 64 bits.
  43  *
  44  * SOURCE
  45  *
  46  */
  47 /****s* silcutil/SilcTimeStruct
  48  *
  49  * NAME
  50  *
  51  *    typedef struct { ... } *SilcTime, SilcTimeStruct;
  52  *
  53  * DESCRIPTION
  54  *
  55  *    This context represents time value.  It includes date and time
  56  *    down to millisecond precision.  The structure size is 64 bits.
  57  *
  58  * SOURCE
  59  *
  60  */
  61 typedef struct SilcTimeObject {
  62   unsigned int year       : 15;    /* Year,     0 - 32768 */
  63   unsigned int month      : 4;     /* Month,    1 - 12 */
  64   unsigned int day        : 5;     /* Day,      1 - 31 */
  65   unsigned int hour       : 5;     /* Hour,     0 - 23 */
  66   unsigned int minute     : 6;     /* Minute,   0 - 59 */
  67   unsigned int second     : 6;     /* Second,   0 - 61 */
  68   unsigned int msecond    : 10;    /* Millisec, 0 - 1000 */
  69   unsigned int utc_hour   : 5;     /* Offset to Zulu (UTC) hours */
  70   unsigned int utc_minute : 6;     /* Offset to Zulu (UTC) minutes */
  71   unsigned int utc_east   : 1;     /* Offset, 1 east (+), 0 west (-) */
  72   unsigned int dst        : 1;     /* Set if daylight saving time */
  73 } *SilcTime, SilcTimeStruct;
  74 /***/
  75
  76 /****f* silcutil/silc_time
  77  *
  78  * SYNOPSIS
  79  *
  80  *    SilcInt64 silc_time(void);
  81  *
  82  * DESCRIPTION
  83  *
  84  *    Returns the current time of the system since Epoch.  The returned
  85  *    value is seconds since Epoch (1.1.1970).  Returns -1 on error.
  86  *
  87  ***/
  88 SilcInt64 silc_time(void);
  89
  90 /****f* silcutil/silc_time_msec
  91  *
  92  * SYNOPSIS
  93  *
  94  *    SilcInt64 silc_time_msec(void);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Returns the current time of the system since Epoch in millisecond
  99  *    resolution.  Returns - 1 on error.
 100  *
 101  ***/
 102 SilcInt64 silc_time_msec(void);
 103
 104 /****f* silcutil/silc_time_usec
 105  *
 106  * SYNOPSIS
 107  *
 108  *    SilcInt64 silc_time_usec(void);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Returns the current time of the system since Epoch in microsecond
 113  *    resolution.  Returns - 1 on error.
 114  *
 115  ***/
 116 SilcInt64 silc_time_usec(void);
 117
 118 /****f* silcutil/silc_time_string
 119  *
 120  * SYNOPSIS
 121  *
 122  *    const char *silc_time_string(SilcInt64 time_val_sec);
 123  *
 124  * DESCRIPTION
 125  *
 126  *    Returns time and date as string.  The caller must not free the string
 127  *    and next call to this function will delete the old string.  If the
 128  *    `time_val_sec' is zero (0) returns current time as string, otherwise the
 129  *    `time_val_sec' as string.  The `time_val_sec' is in seconds since Epoch.
 130  *    Returns NULL on error.
 131  *
 132  ***/
 133 const char *silc_time_string(SilcInt64 time_val_sec);
 134
 135 /****f* silcutil/silc_time_value
 136  *
 137  * SYNOPSIS
 138  *
 139  *   SilcBool silc_time_value(SilcInt64 time_val_msec, SilcTime ret_time);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Returns time and date as SilcTime.  If the `time_val_msec' is zero (0)
 144  *    returns current time as SilcTime, otherwise the `time_val_msec' as
 145  *    SilcTime.  The `time_val_msec' is in milliseconds since Epoch.  Returns
 146  *    FALSE on error, TRUE otherwise.
 147  *
 148  ***/
 149 SilcBool silc_time_value(SilcInt64 time_val_msec, SilcTime ret_time);
 150
 151 /****f* silcutil/silc_timezone
 152  *
 153  * SYNOPSIS
 154  *
 155  *    SilcBool silc_timezone(char *timezone, SilcUInt32 timezone_size);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Returns current timezone in Universal time format into the `timezone'
 160  *    buffer of size of `timezone_size'.  The possible values this function
 161  *    returns are: Z (For UTC timezone), +hh (UTC + hours) -hh (UTC - hours),
 162  *    +hh:mm (UTC + hours:minutes) or -hh:mm (UTC - hours:minutes).  The
 163  *    returned values are always offsets to UTC.
 164  *
 165  *    Returns FALSE on error, TRUE otherwise.
 166  *
 167  ***/
 168 SilcBool silc_timezone(char *timezone, SilcUInt32 timezone_size);
 169
 170 /****f* silcutil/silc_time_universal
 171  *
 172  * SYNOPSIS
 173  *
 174  *    SilcBool silc_time_universal(const char *universal_time,
 175  *                                 SilcTime ret_time);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Returns time and date as SilcTime from `universal_time' string which
 180  *    format is "YYMMDDhhmmssZ", where YY is year, MM is month, DD is day,
 181  *    hh is hour, mm is minutes, ss is seconds and Z is timezone, which
 182  *    by default is Zulu (UTC).  Universal time is defined in ISO/EIC 8824-1.
 183  *
 184  *    Returns FALSE on error, TRUE otherwise.
 185  *
 186  * EXAMPLE
 187  *
 188  *    SilcTimeStruct ret_time;
 189  *
 190  *    time is 03/02/19 19:04:03 Zulu (UTC)
 191  *    silc_time_universal("030219190403Z", &ret_time);
 192  *
 193  ***/
 194 SilcBool silc_time_universal(const char *universal_time, SilcTime ret_time);
 195
 196 /****f* silcutil/silc_time_universal_string
 197  *
 198  * SYNOPSIS
 199  *
 200  *    SilcBool silc_time_universal_string(SilcTime time_val, char *ret_string,
 201  *                                        SilcUInt32 ret_string_size);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Encodes the SilcTime `time' into the universal time format into the
 206  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 207  *
 208  ***/
 209 SilcBool silc_time_universal_string(SilcTime time_val, char *ret_string,
 210                                     SilcUInt32 ret_string_size);
 211
 212 /****f* silcutil/silc_time_generalized
 213  *
 214  * SYNOPSIS
 215  *
 216  *    SilcBool silc_time_generalized(const char *generalized_time,
 217  *                                   SilcTime ret_time);
 218  *
 219  * DESCRIPTION
 220  *
 221  *    Returns time and date as SilcTime from `generalized_time' string which
 222  *    format is "YYYYMMDDhhmmss.ppZ", where YYYY is year, MM is month, DD
 223  *    is day, hh is hour, mm is minutes, ss is seconds which may have optional
 224  *    precision pp, and Z is timezone, which by default is Zulu (UTC).
 225  *    Generalized time is defined in ISO/EIC 8824-1.
 226  *
 227  *    Returns FALSE on error, TRUE otherwise.
 228  *
 229  * EXAMPLE
 230  *
 231  *    SilcTimeStruct ret_time;
 232  *
 233  *    time is 2003/02/19 19:04:03 Zulu (UTC)
 234  *    silc_time_generalized("20030219190403Z", &ret_time);
 235  *
 236  *    time is 2003/02/19 19:05:10.212 Zulu (UTC)
 237  *    silc_time_generalized("20030219190510.212Z", &ret_time);
 238  *
 239  ***/
 240 SilcBool
 241 silc_time_generalized(const char *generalized_time, SilcTime ret_time);
 242
 243 /****f* silcutil/silc_time_generalized_string
 244  *
 245  * SYNOPSIS
 246  *
 247  *    SilcBool silc_time_generalized_string(SilcTime time_val,
 248  *                                          char *ret_string,
 249  *                                          SilcUInt32 ret_string_size);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Encodes the SilcTime `time' into the generalized time format into the
 254  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 255  *
 256  ***/
 257 SilcBool silc_time_generalized_string(SilcTime time_val, char *ret_string,
 258                                       SilcUInt32 ret_string_size);
 259
 260 /****f* silcutil/silc_compare_timeval
 261  *
 262  * SYNOPSIS
 263  *
 264  *    int silc_compare_timeval(struct time_val *t1, struct time_val *t2);
 265  *
 266  * DESCRIPTION
 267  *
 268  *    Compares `t1' and `t2' time structures and returns less than zero,
 269  *    zero or more than zero when `t1' is smaller, equal or bigger than
 270  *    `t2', respectively.
 271  *
 272  ***/
 273 int silc_compare_timeval(struct timeval *t1, struct timeval *t2);
 274
 275 /****f* silcutil/silc_gettimeofday
 276  *
 277  * SYNOPSIS
 278  *
 279  *    int silc_gettimeofday(struct timeval *p);
 280  *
 281  * DESCRIPTION
 282  *
 283  *    Return current time to struct timeval.  This function is system
 284  *    dependant.  Returns 0 on success and -1 on error.
 285  *
 286  ***/
 287 int silc_gettimeofday(struct timeval *p);
 288
 289 #endif /* SILCTIME_H */