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_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 milliseconds as an apr_time_t */ 00075 #define apr_time_from_msec(msec) ((apr_time_t)(msec) * 1000) 00076 00077 /** @return seconds as an apr_time_t */ 00078 #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC) 00079 00080 /** @return a second and usec combination as an apr_time_t */ 00081 #define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \ 00082 + (apr_time_t)(usec)) 00083 00084 /** 00085 * @return the current time 00086 */ 00087 APR_DECLARE(apr_time_t) apr_time_now(void); 00088 00089 /** @see apr_time_exp_t */ 00090 typedef struct apr_time_exp_t apr_time_exp_t; 00091 00092 /** 00093 * a structure similar to ANSI struct tm with the following differences: 00094 * - tm_usec isn't an ANSI field 00095 * - tm_gmtoff isn't an ANSI field (it's a BSDism) 00096 */ 00097 struct apr_time_exp_t { 00098 /** microseconds past tm_sec */ 00099 apr_int32_t tm_usec; 00100 /** (0-61) seconds past tm_min */ 00101 apr_int32_t tm_sec; 00102 /** (0-59) minutes past tm_hour */ 00103 apr_int32_t tm_min; 00104 /** (0-23) hours past midnight */ 00105 apr_int32_t tm_hour; 00106 /** (1-31) day of the month */ 00107 apr_int32_t tm_mday; 00108 /** (0-11) month of the year */ 00109 apr_int32_t tm_mon; 00110 /** year since 1900 */ 00111 apr_int32_t tm_year; 00112 /** (0-6) days since Sunday */ 00113 apr_int32_t tm_wday; 00114 /** (0-365) days since January 1 */ 00115 apr_int32_t tm_yday; 00116 /** daylight saving time */ 00117 apr_int32_t tm_isdst; 00118 /** seconds east of UTC */ 00119 apr_int32_t tm_gmtoff; 00120 }; 00121 00122 /* Delayed the include to avoid a circular reference */ 00123 #include "apr_pools.h" 00124 00125 /** 00126 * Convert an ansi time_t to an apr_time_t 00127 * @param result the resulting apr_time_t 00128 * @param input the time_t to convert 00129 */ 00130 APR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result, 00131 time_t input); 00132 00133 /** 00134 * Convert a time to its human readable components using an offset 00135 * from GMT. 00136 * @param result the exploded time 00137 * @param input the time to explode 00138 * @param offs the number of seconds offset to apply 00139 */ 00140 APR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result, 00141 apr_time_t input, 00142 apr_int32_t offs); 00143 00144 /** 00145 * Convert a time to its human readable components (GMT). 00146 * @param result the exploded time 00147 * @param input the time to explode 00148 */ 00149 APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, 00150 apr_time_t input); 00151 00152 /** 00153 * Convert a time to its human readable components in the local timezone. 00154 * @param result the exploded time 00155 * @param input the time to explode 00156 */ 00157 APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, 00158 apr_time_t input); 00159 00160 /** 00161 * Convert time value from human readable format to a numeric apr_time_t 00162 * (elapsed microseconds since the epoch). 00163 * @param result the resulting imploded time 00164 * @param input the input exploded time 00165 */ 00166 APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, 00167 apr_time_exp_t *input); 00168 00169 /** 00170 * Convert time value from human readable format to a numeric apr_time_t that 00171 * always represents GMT. 00172 * @param result the resulting imploded time 00173 * @param input the input exploded time 00174 */ 00175 APR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result, 00176 apr_time_exp_t *input); 00177 00178 /** 00179 * Sleep for the specified number of micro-seconds. 00180 * @param t desired amount of time to sleep. 00181 * @warning May sleep for longer than the specified time. 00182 */ 00183 APR_DECLARE(void) apr_sleep(apr_interval_time_t t); 00184 00185 /** length of a RFC822 Date */ 00186 #define APR_RFC822_DATE_LEN (30) 00187 /** 00188 * apr_rfc822_date formats dates in the RFC822 00189 * format in an efficient manner. It is a fixed length 00190 * format which requires APR_RFC822_DATA_LEN bytes of storage, 00191 * including the trailing NUL terminator. 00192 * @param date_str String to write to. 00193 * @param t the time to convert 00194 */ 00195 APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t); 00196 00197 /** length of a CTIME date */ 00198 #define APR_CTIME_LEN (25) 00199 /** 00200 * apr_ctime formats dates in the ctime() format 00201 * in an efficient manner. It is a fixed length format 00202 * and requires APR_CTIME_LEN bytes of storage including 00203 * the trailing NUL terminator. 00204 * Unlike ANSI/ISO C ctime(), apr_ctime() does not include 00205 * a \\n at the end of the string. 00206 * @param date_str String to write to. 00207 * @param t the time to convert 00208 */ 00209 APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t); 00210 00211 /** 00212 * Formats the exploded time according to the format specified 00213 * @param s string to write to 00214 * @param retsize The length of the returned string 00215 * @param max The maximum length of the string 00216 * @param format The format for the time string 00217 * @param tm The time to convert 00218 */ 00219 APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, 00220 apr_size_t max, const char *format, 00221 apr_time_exp_t *tm); 00222 00223 /** 00224 * Improve the clock resolution for the lifetime of the given pool. 00225 * Generally this is only desirable on benchmarking and other very 00226 * time-sensitive applications, and has no impact on most platforms. 00227 * @param p The pool to associate the finer clock resolution 00228 */ 00229 APR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p); 00230 00231 /** @} */ 00232 00233 #ifdef __cplusplus 00234 } 00235 #endif 00236 00237 #endif /* ! APR_TIME_H */
1.5.6