lib/silcutil/silctime.h

   1 /*
   2
   3   silctime.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2007 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/SILC 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/SilcTimeAPI/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 typedef struct SilcTimeObject {
  48   unsigned int year       : 15;    /* Year,     0 - 32768 */
  49   unsigned int month      : 4;     /* Month,    1 - 12 */
  50   unsigned int day        : 5;     /* Day,      1 - 31 */
  51   unsigned int hour       : 5;     /* Hour,     0 - 23 */
  52   unsigned int minute     : 6;     /* Minute,   0 - 59 */
  53   unsigned int second     : 6;     /* Second,   0 - 61 */
  54   unsigned int msecond    : 10;    /* Millisec, 0 - 1000 */
  55   unsigned int utc_hour   : 5;     /* Offset to Zulu (UTC) hours */
  56   unsigned int utc_minute : 6;     /* Offset to Zulu (UTC) minutes */
  57   unsigned int utc_east   : 1;     /* Offset, 1 east (+), 0 west (-) */
  58   unsigned int dst        : 1;     /* Set if daylight saving time */
  59 } *SilcTime, SilcTimeStruct;
  60 /***/
  61
  62 /****f* silcutil/SilcTimeAPI/silc_time
  63  *
  64  * SYNOPSIS
  65  *
  66  *    SilcInt64 silc_time(void);
  67  *
  68  * DESCRIPTION
  69  *
  70  *    Returns the current time of the system since Epoch.  The returned
  71  *    value is seconds since Epoch (1.1.1970).  Returns -1 on error.
  72  *
  73  ***/
  74 SilcInt64 silc_time(void);
  75
  76 /****f* silcutil/SilcTimeAPI/silc_time_msec
  77  *
  78  * SYNOPSIS
  79  *
  80  *    SilcInt64 silc_time_msec(void);
  81  *
  82  * DESCRIPTION
  83  *
  84  *    Returns the current time of the system since Epoch in millisecond
  85  *    resolution.  Returns - 1 on error.
  86  *
  87  ***/
  88 SilcInt64 silc_time_msec(void);
  89
  90 /****f* silcutil/SilcTimeAPI/silc_time_usec
  91  *
  92  * SYNOPSIS
  93  *
  94  *    SilcInt64 silc_time_usec(void);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Returns the current time of the system since Epoch in microsecond
  99  *    resolution.  Returns - 1 on error.
 100  *
 101  ***/
 102 SilcInt64 silc_time_usec(void);
 103
 104 /****f* silcutil/SilcTimeAPI/silc_time_string
 105  *
 106  * SYNOPSIS
 107  *
 108  *    const char *silc_time_string(SilcInt64 time_val_sec);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Returns time and date as string.  The caller must not free the string
 113  *    and next call to this function will delete the old string.  If the
 114  *    `time_val_sec' is zero (0) returns current time as string, otherwise the
 115  *    `time_val_sec' as string.  The `time_val_sec' is in seconds since Epoch.
 116  *    Returns NULL on error.
 117  *
 118  ***/
 119 const char *silc_time_string(SilcInt64 time_val_sec);
 120
 121 /****f* silcutil/SilcTimeAPI/silc_time_value
 122  *
 123  * SYNOPSIS
 124  *
 125  *   SilcBool silc_time_value(SilcInt64 time_val_msec, SilcTime ret_time);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Returns time and date as SilcTime.  If the `time_val_msec' is zero (0)
 130  *    returns current time as SilcTime, otherwise the `time_val_msec' as
 131  *    SilcTime.  The `time_val_msec' is in milliseconds since Epoch.  Returns
 132  *    FALSE on error, TRUE otherwise.
 133  *
 134  ***/
 135 SilcBool silc_time_value(SilcInt64 time_val_msec, SilcTime ret_time);
 136
 137 /****f* silcutil/SilcTimeAPI/silc_timezone
 138  *
 139  * SYNOPSIS
 140  *
 141  *    SilcBool silc_timezone(char *timezone, SilcUInt32 timezone_size);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Returns current timezone in Universal time format into the `timezone'
 146  *    buffer of size of `timezone_size'.  The possible values this function
 147  *    returns are: Z (For UTC timezone), +hh (UTC + hours) -hh (UTC - hours),
 148  *    +hh:mm (UTC + hours:minutes) or -hh:mm (UTC - hours:minutes).  The
 149  *    returned values are always offsets to UTC.
 150  *
 151  *    Returns FALSE on error, TRUE otherwise.
 152  *
 153  ***/
 154 SilcBool silc_timezone(char *timezone, SilcUInt32 timezone_size);
 155
 156 /****f* silcutil/SilcTimeAPI/silc_time_universal
 157  *
 158  * SYNOPSIS
 159  *
 160  *    SilcBool silc_time_universal(const char *universal_time,
 161  *                                 SilcTime ret_time);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Returns time and date as SilcTime from `universal_time' string which
 166  *    format is "YYMMDDhhmmssZ", where YY is year, MM is month, DD is day,
 167  *    hh is hour, mm is minutes, ss is seconds and Z is timezone, which
 168  *    by default is Zulu (UTC).  Universal time is defined in ISO/EIC 8824-1.
 169  *
 170  *    Returns FALSE on error, TRUE otherwise.
 171  *
 172  * EXAMPLE
 173  *
 174  *    SilcTimeStruct ret_time;
 175  *
 176  *    time is 03/02/19 19:04:03 Zulu (UTC)
 177  *    silc_time_universal("030219190403Z", &ret_time);
 178  *
 179  ***/
 180 SilcBool silc_time_universal(const char *universal_time, SilcTime ret_time);
 181
 182 /****f* silcutil/SilcTimeAPI/silc_time_universal_string
 183  *
 184  * SYNOPSIS
 185  *
 186  *    SilcBool silc_time_universal_string(SilcTime time_val, char *ret_string,
 187  *                                        SilcUInt32 ret_string_size);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Encodes the SilcTime `time' into the universal time format into the
 192  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 193  *
 194  ***/
 195 SilcBool silc_time_universal_string(SilcTime time_val, char *ret_string,
 196                                     SilcUInt32 ret_string_size);
 197
 198 /****f* silcutil/SilcTimeAPI/silc_time_generalized
 199  *
 200  * SYNOPSIS
 201  *
 202  *    SilcBool silc_time_generalized(const char *generalized_time,
 203  *                                   SilcTime ret_time);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Returns time and date as SilcTime from `generalized_time' string which
 208  *    format is "YYYYMMDDhhmmss.ppZ", where YYYY is year, MM is month, DD
 209  *    is day, hh is hour, mm is minutes, ss is seconds which may have optional
 210  *    precision pp, and Z is timezone, which by default is Zulu (UTC).
 211  *    Generalized time is defined in ISO/EIC 8824-1.
 212  *
 213  *    Returns FALSE on error, TRUE otherwise.
 214  *
 215  * EXAMPLE
 216  *
 217  *    SilcTimeStruct ret_time;
 218  *
 219  *    time is 2003/02/19 19:04:03 Zulu (UTC)
 220  *    silc_time_generalized("20030219190403Z", &ret_time);
 221  *
 222  *    time is 2003/02/19 19:05:10.212 Zulu (UTC)
 223  *    silc_time_generalized("20030219190510.212Z", &ret_time);
 224  *
 225  ***/
 226 SilcBool
 227 silc_time_generalized(const char *generalized_time, SilcTime ret_time);
 228
 229 /****f* silcutil/SilcTimeAPI/silc_time_generalized_string
 230  *
 231  * SYNOPSIS
 232  *
 233  *    SilcBool silc_time_generalized_string(SilcTime time_val,
 234  *                                          char *ret_string,
 235  *                                          SilcUInt32 ret_string_size);
 236  *
 237  * DESCRIPTION
 238  *
 239  *    Encodes the SilcTime `time' into the generalized time format into the
 240  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 241  *
 242  ***/
 243 SilcBool silc_time_generalized_string(SilcTime time_val, char *ret_string,
 244                                       SilcUInt32 ret_string_size);
 245
 246 /****f* silcutil/SilcTimeAPI/silc_compare_timeval
 247  *
 248  * SYNOPSIS
 249  *
 250  *    int silc_compare_timeval(struct time_val *t1, struct time_val *t2);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Compares `t1' and `t2' time structures and returns less than zero,
 255  *    zero or more than zero when `t1' is smaller, equal or bigger than
 256  *    `t2', respectively.
 257  *
 258  ***/
 259 int silc_compare_timeval(struct timeval *t1, struct timeval *t2);
 260
 261 /****f* silcutil/SilcTimeAPI/silc_gettimeofday
 262  *
 263  * SYNOPSIS
 264  *
 265  *    int silc_gettimeofday(struct timeval *p);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Return current time to struct timeval.  This function is system
 270  *    dependant.  Returns 0 on success and -1 on error.
 271  *
 272  ***/
 273 int silc_gettimeofday(struct timeval *p);
 274
 275 /****f* silcutil/SilcTimeAPI/silc_usleep
 276  *
 277  * SYNOPSIS
 278  *
 279  *    void silc_usleep(unsigned long microseconds);
 280  *
 281  * DESCRIPTION
 282  *
 283  *    Delays the execution of process/thread for the specified amount of
 284  *    time, which is in microseconds.
 285  *
 286  * NOTES
 287  *
 288  *    The delay is only approximate and on some platforms the resolution is
 289  *    in fact milliseconds.
 290  *
 291  ***/
 292 static inline
 293 void silc_usleep(unsigned long microseconds)
 294 {
 295 #ifdef SILC_UNIX
 296 #ifdef HAVE_NANOSLEEP
 297   struct timespec tv;
 298   tv.tv_sec = 0;
 299   tv.tv_nsec = microseconds * 1000;
 300 #endif /* HAVE_NANOSLEEP */
 301 #endif /* SILC_UNIX */
 302
 303 #ifdef SILC_UNIX
 304 #ifdef HAVE_NANOSLEEP
 305   nanosleep(&tv, NULL);
 306 #else
 307   usleep(microseconds);
 308 #endif /* HAVE_NANOSLEEP */
 309 #endif /* SILC_UNIX */
 310 #ifdef SILC_WIN32
 311   Sleep(microseconds / 1000);
 312 #endif /* SILC_WIN32 */
 313 #ifdef SILC_SYMBIAN
 314   silc_symbian_usleep(microseconds);
 315 #endif /* SILC_SYMBIAN */
 316 }
 317
 318 #endif /* SILCTIME_H */