00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_TIME_H 00017 #define APR_TIME_H 00018 00019 /** 00020 * @file apr_time.h 00021 * @brief APR Time Library 00022 */ 00023 00024 #include "apr.h" 00025 #include "apr_pools.h" 00026 #include "apr_errno.h" 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif /* __cplusplus */ 00031 00032 /** 00033 * @defgroup apr_time Time Routines 00034 * @ingroup APR 00035 * @{ 00036 */ 00037 00038 /** month names */ 00039 APR_DECLARE_DATA extern const char apr_month_snames[12][4]; 00040 /** day names */ 00041 APR_DECLARE_DATA extern const char apr_day_snames[7][4]; 00042 00043 00044 /** number of microseconds since 00:00:00 january 1, 1970 UTC */ 00045 typedef apr_int64_t apr_time_t; 00046 00047 00048 /** mechanism to properly type apr_time_t literals */ 00049 #define APR_TIME_C(val) APR_INT64_C(val) 00050 00051 /** mechanism to properly print apr_time_t values */ 00052 #define APR_TIME_T_FMT APR_INT64_T_FMT 00053 00054 /** intervals for I/O timeouts, in microseconds */ 00055 typedef apr_int64_t apr_interval_time_t; 00056 /** short interval for I/O timeouts, in microseconds */ 00057 typedef apr_int32_t apr_short_interval_time_t; 00058 00059 /** number of microseconds per second */ 00060 #define APR_USEC_PER_SEC APR_TIME_C(1000000) 00061 00062 /** @return apr_time_t as a second */ 00063 #define apr_time_sec(time) ((time) / APR_USEC_PER_SEC) 00064 00065 /** @return apr_time_t as a usec */ 00066 #define apr_time_usec(time) ((time) % APR_USEC_PER_SEC) 00067 00068 /** @return apr_time_t as a msec */ 00069 #define apr_time_msec(time) (((time) / 1000) % 1000) 00070 00071 /** @return apr_time_t as a msec */ 00072 #define apr_time_as_msec(time) ((time) / 1000) 00073 00074 /** @return a second as an apr_time_t */ 00075 #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC) 00076 00077 /** @return a second and usec combination as an apr_time_t */ 00078 #define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \ 00079 + (apr_time_t)(usec)) 00080 00081 /** 00082 * @return the current time 00083 */ 00084 APR_DECLARE(apr_time_t) apr_time_now(void); 00085 00086 /** @see apr_time_exp_t */ 00087 typedef struct apr_time_exp_t apr_time_exp_t; 00088 00089 /** 00090 * a structure similar to ANSI struct tm with the following differences: 00091 * - tm_usec isn't an ANSI field 00092 * - tm_gmtoff isn't an ANSI field (it's a bsdism) 00093 */ 00094 struct apr_time_exp_t { 00095 /** microseconds past tm_sec */ 00096 apr_int32_t tm_usec; 00097 /** (0-61) seconds past tm_min */ 00098 apr_int32_t tm_sec; 00099 /** (0-59) minutes past tm_hour */ 00100 apr_int32_t tm_min; 00101 /** (0-23) hours past midnight */ 00102 apr_int32_t tm_hour; 00103 /** (1-31) day of the month */ 00104 apr_int32_t tm_mday; 00105 /** (0-11) month of the year */ 00106 apr_int32_t tm_mon; 00107 /** year since 1900 */ 00108 apr_int32_t tm_year; 00109 /** (0-6) days since sunday */ 00110 apr_int32_t tm_wday; 00111 /** (0-365) days since jan 1 */ 00112 apr_int32_t tm_yday; 00113 /** daylight saving time */ 00114 apr_int32_t tm_isdst; 00115 /** seconds east of UTC */ 00116 apr_int32_t tm_gmtoff; 00117 }; 00118 00119 /** 00120 * convert an ansi time_t to an apr_time_t 00121 * @param result the resulting apr_time_t 00122 * @param input the time_t to convert 00123 */ 00124 APR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result, 00125 time_t input); 00126 00127 /** 00128 * convert a time to its human readable components using an offset 00129 * from GMT 00130 * @param result the exploded time 00131 * @param input the time to explode 00132 * @param offs the number of seconds offset to apply 00133 */ 00134 APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result, 00135 apr_time_t input, 00136 apr_int32_t offs); 00137 00138 /** 00139 * convert a time to its human readable components in GMT timezone 00140 * @param result the exploded time 00141 * @param input the time to explode 00142 */ 00143 APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, 00144 apr_time_t input); 00145 00146 /** 00147 * convert a time to its human readable components in local timezone 00148 * @param result the exploded time 00149 * @param input the time to explode 00150 */ 00151 APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, 00152 apr_time_t input); 00153 00154 /** 00155 * Convert time value from human readable format to a numeric apr_time_t 00156 * e.g. elapsed usec since epoch 00157 * @param result the resulting imploded time 00158 * @param input the input exploded time 00159 */ 00160 APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, 00161 apr_time_exp_t *input); 00162 00163 /** 00164 * Convert time value from human readable format to a numeric apr_time_t that 00165 * always represents GMT 00166 * @param result the resulting imploded time 00167 * @param input the input exploded time 00168 */ 00169 APR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result, 00170 apr_time_exp_t *input); 00171 00172 /** 00173 * Sleep for the specified number of micro-seconds. 00174 * @param t desired amount of time to sleep. 00175 * @warning May sleep for longer than the specified time. 00176 */ 00177 APR_DECLARE(void) apr_sleep(apr_interval_time_t t); 00178 00179 /** length of a RFC822 Date */ 00180 #define APR_RFC822_DATE_LEN (30) 00181 /** 00182 * apr_rfc822_date formats dates in the RFC822 00183 * format in an efficient manner. It is a fixed length 00184 * format which requires the indicated amount of storage, 00185 * including the trailing NUL terminator. 00186 * @param date_str String to write to. 00187 * @param t the time to convert 00188 */ 00189 APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t); 00190 00191 /** length of a CTIME date */ 00192 #define APR_CTIME_LEN (25) 00193 /** 00194 * apr_ctime formats dates in the ctime() format 00195 * in an efficient manner. it is a fixed length format 00196 * and requires the indicated amount of storage including 00197 * the trailing NUL terminator. 00198 * Unlike ANSI/ISO C ctime(), apr_ctime() does not include 00199 * a \n at the end of the string. 00200 * @param date_str String to write to. 00201 * @param t the time to convert 00202 */ 00203 APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t); 00204 00205 /** 00206 * formats the exploded time according to the format specified 00207 * @param s string to write to 00208 * @param retsize The length of the returned string 00209 * @param max The maximum length of the string 00210 * @param format The format for the time string 00211 * @param tm The time to convert 00212 */ 00213 APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, 00214 apr_size_t max, const char *format, 00215 apr_time_exp_t *tm); 00216 00217 /** 00218 * Improve the clock resolution for the lifetime of the given pool. 00219 * Generally this is only desireable on benchmarking and other very 00220 * time-sensitive applications, and has no impact on most platforms. 00221 * @param p The pool to associate the finer clock resolution 00222 */ 00223 APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p); 00224 00225 /** @} */ 00226 00227 #ifdef __cplusplus 00228 } 00229 #endif 00230 00231 #endif /* ! APR_TIME_H */