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