contrib/apr/include/apr_time.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef APR_TIME_H
  18 #define APR_TIME_H
  19
  20 /**
  21  * @file apr_time.h
  22  * @brief APR Time Library
  23  */
  24
  25 #include "apr.h"
  26 #include "apr_pools.h"
  27 #include "apr_errno.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 /**
  34  * @defgroup apr_time Time Routines
  35  * @ingroup APR
  36  * @{
  37  */
  38
  39 /** month names */
  40 APR_DECLARE_DATA extern const char apr_month_snames[12][4];
  41 /** day names */
  42 APR_DECLARE_DATA extern const char apr_day_snames[7][4];
  43
  44
  45 /** number of microseconds since 00:00:00 january 1, 1970 UTC */
  46 typedef apr_int64_t apr_time_t;
  47
  48
  49 /** mechanism to properly type apr_time_t literals */
  50 #define APR_TIME_C(val) APR_INT64_C(val)
  51
  52 /** mechanism to properly print apr_time_t values */
  53 #define APR_TIME_T_FMT APR_INT64_T_FMT
  54
  55 /** intervals for I/O timeouts, in microseconds */
  56 typedef apr_int64_t apr_interval_time_t;
  57 /** short interval for I/O timeouts, in microseconds */
  58 typedef apr_int32_t apr_short_interval_time_t;
  59
  60 /** number of microseconds per second */
  61 #define APR_USEC_PER_SEC APR_TIME_C(1000000)
  62
  63 /** @return apr_time_t as a second */
  64 #define apr_time_sec(time) ((time) / APR_USEC_PER_SEC)
  65
  66 /** @return apr_time_t as a usec */
  67 #define apr_time_usec(time) ((time) % APR_USEC_PER_SEC)
  68
  69 /** @return apr_time_t as a msec */
  70 #define apr_time_msec(time) (((time) / 1000) % 1000)
  71
  72 /** @return apr_time_t as a msec */
  73 #define apr_time_as_msec(time) ((time) / 1000)
  74
  75 /** @return milliseconds as an apr_time_t */
  76 #define apr_time_from_msec(msec) ((apr_time_t)(msec) * 1000)
  77
  78 /** @return seconds as an apr_time_t */
  79 #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC)
  80
  81 /** @return a second and usec combination as an apr_time_t */
  82 #define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \
  83                                 + (apr_time_t)(usec))
  84
  85 /**
  86  * @return the current time
  87  */
  88 APR_DECLARE(apr_time_t) apr_time_now(void);
  89
  90 /** @see apr_time_exp_t */
  91 typedef struct apr_time_exp_t apr_time_exp_t;
  92
  93 /**
  94  * a structure similar to ANSI struct tm with the following differences:
  95  *  - tm_usec isn't an ANSI field
  96  *  - tm_gmtoff isn't an ANSI field (it's a bsdism)
  97  */
  98 struct apr_time_exp_t {
  99     /** microseconds past tm_sec */
 100     apr_int32_t tm_usec;
 101     /** (0-61) seconds past tm_min */
 102     apr_int32_t tm_sec;
 103     /** (0-59) minutes past tm_hour */
 104     apr_int32_t tm_min;
 105     /** (0-23) hours past midnight */
 106     apr_int32_t tm_hour;
 107     /** (1-31) day of the month */
 108     apr_int32_t tm_mday;
 109     /** (0-11) month of the year */
 110     apr_int32_t tm_mon;
 111     /** year since 1900 */
 112     apr_int32_t tm_year;
 113     /** (0-6) days since sunday */
 114     apr_int32_t tm_wday;
 115     /** (0-365) days since jan 1 */
 116     apr_int32_t tm_yday;
 117     /** daylight saving time */
 118     apr_int32_t tm_isdst;
 119     /** seconds east of UTC */
 120     apr_int32_t tm_gmtoff;
 121 };
 122
 123 /**
 124  * convert an ansi time_t to an apr_time_t
 125  * @param result the resulting apr_time_t
 126  * @param input the time_t to convert
 127  */
 128 APR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result,
 129                                                     time_t input);
 130
 131 /**
 132  * convert a time to its human readable components using an offset
 133  * from GMT
 134  * @param result the exploded time
 135  * @param input the time to explode
 136  * @param offs the number of seconds offset to apply
 137  */
 138 APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result,
 139                                           apr_time_t input,
 140                                           apr_int32_t offs);
 141
 142 /**
 143  * convert a time to its human readable components in GMT timezone
 144  * @param result the exploded time
 145  * @param input the time to explode
 146  */
 147 APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result,
 148                                            apr_time_t input);
 149
 150 /**
 151  * convert a time to its human readable components in local timezone
 152  * @param result the exploded time
 153  * @param input the time to explode
 154  */
 155 APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result,
 156                                           apr_time_t input);
 157
 158 /**
 159  * Convert time value from human readable format to a numeric apr_time_t
 160  * e.g. elapsed usec since epoch
 161  * @param result the resulting imploded time
 162  * @param input the input exploded time
 163  */
 164 APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result,
 165                                            apr_time_exp_t *input);
 166
 167 /**
 168  * Convert time value from human readable format to a numeric apr_time_t that
 169  * always represents GMT
 170  * @param result the resulting imploded time
 171  * @param input the input exploded time
 172  */
 173 APR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result,
 174                                                apr_time_exp_t *input);
 175
 176 /**
 177  * Sleep for the specified number of micro-seconds.
 178  * @param t desired amount of time to sleep.
 179  * @warning May sleep for longer than the specified time.
 180  */
 181 APR_DECLARE(void) apr_sleep(apr_interval_time_t t);
 182
 183 /** length of a RFC822 Date */
 184 #define APR_RFC822_DATE_LEN (30)
 185 /**
 186  * apr_rfc822_date formats dates in the RFC822
 187  * format in an efficient manner.  It is a fixed length
 188  * format which requires the indicated amount of storage,
 189  * including the trailing NUL terminator.
 190  * @param date_str String to write to.
 191  * @param t the time to convert
 192  */
 193 APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t);
 194
 195 /** length of a CTIME date */
 196 #define APR_CTIME_LEN (25)
 197 /**
 198  * apr_ctime formats dates in the ctime() format
 199  * in an efficient manner.  it is a fixed length format
 200  * and requires the indicated amount of storage including
 201  * the trailing NUL terminator.
 202  * Unlike ANSI/ISO C ctime(), apr_ctime() does not include
 203  * a \n at the end of the string.
 204  * @param date_str String to write to.
 205  * @param t the time to convert
 206  */
 207 APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t);
 208
 209 /**
 210  * formats the exploded time according to the format specified
 211  * @param s string to write to
 212  * @param retsize The length of the returned string
 213  * @param max The maximum length of the string
 214  * @param format The format for the time string
 215  * @param tm The time to convert
 216  */
 217 APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize,
 218                                        apr_size_t max, const char *format,
 219                                        apr_time_exp_t *tm);
 220
 221 /**
 222  * Improve the clock resolution for the lifetime of the given pool.
 223  * Generally this is only desireable on benchmarking and other very
 224  * time-sensitive applications, and has no impact on most platforms.
 225  * @param p The pool to associate the finer clock resolution
 226  */
 227 APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p);
 228
 229 /** @} */
 230
 231 #ifdef __cplusplus
 232 }
 233 #endif
 234
 235 #endif  /* ! APR_TIME_H */