rubbos/app/apache2/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 a second as an apr_time_t */
  76 #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC)
  77
  78 /** @return a second and usec combination as an apr_time_t */
  79 #define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \
  80                                 + (apr_time_t)(usec))
  81
  82 /**
  83  * @return the current time
  84  */
  85 APR_DECLARE(apr_time_t) apr_time_now(void);
  86
  87 /** @see apr_time_exp_t */
  88 typedef struct apr_time_exp_t apr_time_exp_t;
  89
  90 /**
  91  * a structure similar to ANSI struct tm with the following differences:
  92  *  - tm_usec isn't an ANSI field
  93  *  - tm_gmtoff isn't an ANSI field (it's a bsdism)
  94  */
  95 struct apr_time_exp_t {
  96     /** microseconds past tm_sec */
  97     apr_int32_t tm_usec;
  98     /** (0-61) seconds past tm_min */
  99     apr_int32_t tm_sec;
 100     /** (0-59) minutes past tm_hour */
 101     apr_int32_t tm_min;
 102     /** (0-23) hours past midnight */
 103     apr_int32_t tm_hour;
 104     /** (1-31) day of the month */
 105     apr_int32_t tm_mday;
 106     /** (0-11) month of the year */
 107     apr_int32_t tm_mon;
 108     /** year since 1900 */
 109     apr_int32_t tm_year;
 110     /** (0-6) days since sunday */
 111     apr_int32_t tm_wday;
 112     /** (0-365) days since jan 1 */
 113     apr_int32_t tm_yday;
 114     /** daylight saving time */
 115     apr_int32_t tm_isdst;
 116     /** seconds east of UTC */
 117     apr_int32_t tm_gmtoff;
 118 };
 119
 120 /**
 121  * convert an ansi time_t to an apr_time_t
 122  * @param result the resulting apr_time_t
 123  * @param input the time_t to convert
 124  */
 125 APR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result,
 126                                                     time_t input);
 127
 128 /**
 129  * convert a time to its human readable components using an offset
 130  * from GMT
 131  * @param result the exploded time
 132  * @param input the time to explode
 133  * @param offs the number of seconds offset to apply
 134  */
 135 APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result,
 136                                           apr_time_t input,
 137                                           apr_int32_t offs);
 138
 139 /** @deprecated @see apr_time_exp_tz */
 140 APR_DECLARE(apr_status_t) apr_explode_time(apr_time_exp_t *result,
 141                                            apr_time_t input,
 142                                            apr_int32_t offs);
 143
 144 /**
 145  * convert a time to its human readable components in GMT timezone
 146  * @param result the exploded time
 147  * @param input the time to explode
 148  */
 149 APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result,
 150                                            apr_time_t input);
 151
 152 /**
 153  * convert a time to its human readable components in local timezone
 154  * @param result the exploded time
 155  * @param input the time to explode
 156  */
 157 APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result,
 158                                           apr_time_t input);
 159
 160 /** @deprecated @see apr_time_exp_lt */
 161 APR_DECLARE(apr_status_t) apr_explode_localtime(apr_time_exp_t *result,
 162                                                 apr_time_t input);
 163
 164 /**
 165  * Convert time value from human readable format to a numeric apr_time_t
 166  * e.g. elapsed usec since epoch
 167  * @param result the resulting imploded time
 168  * @param input the input exploded time
 169  */
 170 APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result,
 171                                            apr_time_exp_t *input);
 172
 173 /**
 174  * Convert time value from human readable format to a numeric apr_time_t that
 175  * always represents GMT
 176  * @param result the resulting imploded time
 177  * @param input the input exploded time
 178  */
 179 APR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result,
 180                                                apr_time_exp_t *input);
 181
 182 /** @deprecated @see apr_time_exp_gmt_get */
 183 APR_DECLARE(apr_status_t) apr_implode_gmt(apr_time_t *result,
 184                                           apr_time_exp_t *input);
 185
 186 /**
 187  * Sleep for the specified number of micro-seconds.
 188  * @param t desired amount of time to sleep.
 189  * @warning May sleep for longer than the specified time.
 190  */
 191 APR_DECLARE(void) apr_sleep(apr_interval_time_t t);
 192
 193 /** length of a RFC822 Date */
 194 #define APR_RFC822_DATE_LEN (30)
 195 /**
 196  * apr_rfc822_date formats dates in the RFC822
 197  * format in an efficient manner.  It is a fixed length
 198  * format which requires the indicated amount of storage,
 199  * including the trailing null byte.
 200  * @param date_str String to write to.
 201  * @param t the time to convert
 202  */
 203 APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t);
 204
 205 /** length of a CTIME date */
 206 #define APR_CTIME_LEN (25)
 207 /**
 208  * apr_ctime formats dates in the ctime() format
 209  * in an efficient manner.  it is a fixed length format
 210  * and requires the indicated amount of storage including
 211  * the trailing null byte.
 212  * Unlike ANSI/ISO C ctime(), apr_ctime() does not include
 213  * a \n at the end of the string.
 214  * @param date_str String to write to.
 215  * @param t the time to convert
 216  */
 217 APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t);
 218
 219 /**
 220  * formats the exploded time according to the format specified
 221  * @param s string to write to
 222  * @param retsize The length of the returned string
 223  * @param max The maximum length of the string
 224  * @param format The format for the time string
 225  * @param tm The time to convert
 226  */
 227 APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize,
 228                                        apr_size_t max, const char *format,
 229                                        apr_time_exp_t *tm);
 230
 231 /**
 232  * Improve the clock resolution for the lifetime of the given pool.
 233  * Generally this is only desireable on benchmarking and other very
 234  * time-sensitive applications, and has no impact on most platforms.
 235  * @param p The pool to associate the finer clock resolution
 236  */
 237 APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p);
 238
 239 /** @} */
 240
 241 #ifdef __cplusplus
 242 }
 243 #endif
 244
 245 #endif  /* ! APR_TIME_H */