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