1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_TIME_H 18251875Speter#define APR_TIME_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_time.h 22251875Speter * @brief APR Time Library 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_errno.h" 27251875Speter 28251875Speter#ifdef __cplusplus 29251875Speterextern "C" { 30251875Speter#endif /* __cplusplus */ 31251875Speter 32251875Speter/** 33251875Speter * @defgroup apr_time Time Routines 34251875Speter * @ingroup APR 35251875Speter * @{ 36251875Speter */ 37251875Speter 38251875Speter/** month names */ 39251875SpeterAPR_DECLARE_DATA extern const char apr_month_snames[12][4]; 40251875Speter/** day names */ 41251875SpeterAPR_DECLARE_DATA extern const char apr_day_snames[7][4]; 42251875Speter 43251875Speter 44266735Speter/** number of microseconds since 00:00:00 January 1, 1970 UTC */ 45251875Spetertypedef apr_int64_t apr_time_t; 46251875Speter 47251875Speter 48251875Speter/** mechanism to properly type apr_time_t literals */ 49251875Speter#define APR_TIME_C(val) APR_INT64_C(val) 50251875Speter 51251875Speter/** mechanism to properly print apr_time_t values */ 52251875Speter#define APR_TIME_T_FMT APR_INT64_T_FMT 53251875Speter 54251875Speter/** intervals for I/O timeouts, in microseconds */ 55251875Spetertypedef apr_int64_t apr_interval_time_t; 56251875Speter/** short interval for I/O timeouts, in microseconds */ 57251875Spetertypedef apr_int32_t apr_short_interval_time_t; 58251875Speter 59251875Speter/** number of microseconds per second */ 60251875Speter#define APR_USEC_PER_SEC APR_TIME_C(1000000) 61251875Speter 62251875Speter/** @return apr_time_t as a second */ 63251875Speter#define apr_time_sec(time) ((time) / APR_USEC_PER_SEC) 64251875Speter 65251875Speter/** @return apr_time_t as a usec */ 66251875Speter#define apr_time_usec(time) ((time) % APR_USEC_PER_SEC) 67251875Speter 68251875Speter/** @return apr_time_t as a msec */ 69251875Speter#define apr_time_msec(time) (((time) / 1000) % 1000) 70251875Speter 71251875Speter/** @return apr_time_t as a msec */ 72251875Speter#define apr_time_as_msec(time) ((time) / 1000) 73251875Speter 74251875Speter/** @return milliseconds as an apr_time_t */ 75251875Speter#define apr_time_from_msec(msec) ((apr_time_t)(msec) * 1000) 76251875Speter 77251875Speter/** @return seconds as an apr_time_t */ 78251875Speter#define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC) 79251875Speter 80251875Speter/** @return a second and usec combination as an apr_time_t */ 81251875Speter#define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \ 82251875Speter + (apr_time_t)(usec)) 83251875Speter 84251875Speter/** 85251875Speter * @return the current time 86251875Speter */ 87251875SpeterAPR_DECLARE(apr_time_t) apr_time_now(void); 88251875Speter 89251875Speter/** @see apr_time_exp_t */ 90251875Spetertypedef struct apr_time_exp_t apr_time_exp_t; 91251875Speter 92251875Speter/** 93251875Speter * a structure similar to ANSI struct tm with the following differences: 94251875Speter * - tm_usec isn't an ANSI field 95266735Speter * - tm_gmtoff isn't an ANSI field (it's a BSDism) 96251875Speter */ 97251875Speterstruct apr_time_exp_t { 98251875Speter /** microseconds past tm_sec */ 99251875Speter apr_int32_t tm_usec; 100251875Speter /** (0-61) seconds past tm_min */ 101251875Speter apr_int32_t tm_sec; 102251875Speter /** (0-59) minutes past tm_hour */ 103251875Speter apr_int32_t tm_min; 104251875Speter /** (0-23) hours past midnight */ 105251875Speter apr_int32_t tm_hour; 106251875Speter /** (1-31) day of the month */ 107251875Speter apr_int32_t tm_mday; 108251875Speter /** (0-11) month of the year */ 109251875Speter apr_int32_t tm_mon; 110251875Speter /** year since 1900 */ 111251875Speter apr_int32_t tm_year; 112266735Speter /** (0-6) days since Sunday */ 113251875Speter apr_int32_t tm_wday; 114266735Speter /** (0-365) days since January 1 */ 115251875Speter apr_int32_t tm_yday; 116251875Speter /** daylight saving time */ 117251875Speter apr_int32_t tm_isdst; 118251875Speter /** seconds east of UTC */ 119251875Speter apr_int32_t tm_gmtoff; 120251875Speter}; 121251875Speter 122362181Sdim/* Delayed the include to avoid a circular reference */ 123362181Sdim#include "apr_pools.h" 124362181Sdim 125251875Speter/** 126266735Speter * Convert an ansi time_t to an apr_time_t 127251875Speter * @param result the resulting apr_time_t 128251875Speter * @param input the time_t to convert 129251875Speter */ 130251875SpeterAPR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result, 131251875Speter time_t input); 132251875Speter 133251875Speter/** 134266735Speter * Convert a time to its human readable components using an offset 135266735Speter * from GMT. 136251875Speter * @param result the exploded time 137251875Speter * @param input the time to explode 138251875Speter * @param offs the number of seconds offset to apply 139251875Speter */ 140251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result, 141251875Speter apr_time_t input, 142251875Speter apr_int32_t offs); 143251875Speter 144251875Speter/** 145266735Speter * Convert a time to its human readable components (GMT). 146251875Speter * @param result the exploded time 147251875Speter * @param input the time to explode 148251875Speter */ 149251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, 150251875Speter apr_time_t input); 151251875Speter 152251875Speter/** 153266735Speter * Convert a time to its human readable components in the local timezone. 154251875Speter * @param result the exploded time 155251875Speter * @param input the time to explode 156251875Speter */ 157251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, 158251875Speter apr_time_t input); 159251875Speter 160251875Speter/** 161266735Speter * Convert time value from human readable format to a numeric apr_time_t 162266735Speter * (elapsed microseconds since the epoch). 163251875Speter * @param result the resulting imploded time 164251875Speter * @param input the input exploded time 165251875Speter */ 166251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, 167251875Speter apr_time_exp_t *input); 168251875Speter 169251875Speter/** 170251875Speter * Convert time value from human readable format to a numeric apr_time_t that 171266735Speter * always represents GMT. 172251875Speter * @param result the resulting imploded time 173251875Speter * @param input the input exploded time 174251875Speter */ 175251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result, 176251875Speter apr_time_exp_t *input); 177251875Speter 178251875Speter/** 179251875Speter * Sleep for the specified number of micro-seconds. 180251875Speter * @param t desired amount of time to sleep. 181251875Speter * @warning May sleep for longer than the specified time. 182251875Speter */ 183251875SpeterAPR_DECLARE(void) apr_sleep(apr_interval_time_t t); 184251875Speter 185251875Speter/** length of a RFC822 Date */ 186251875Speter#define APR_RFC822_DATE_LEN (30) 187251875Speter/** 188251875Speter * apr_rfc822_date formats dates in the RFC822 189251875Speter * format in an efficient manner. It is a fixed length 190266735Speter * format which requires APR_RFC822_DATA_LEN bytes of storage, 191251875Speter * including the trailing NUL terminator. 192251875Speter * @param date_str String to write to. 193251875Speter * @param t the time to convert 194251875Speter */ 195251875SpeterAPR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t); 196251875Speter 197251875Speter/** length of a CTIME date */ 198251875Speter#define APR_CTIME_LEN (25) 199251875Speter/** 200251875Speter * apr_ctime formats dates in the ctime() format 201266735Speter * in an efficient manner. It is a fixed length format 202266735Speter * and requires APR_CTIME_LEN bytes of storage including 203251875Speter * the trailing NUL terminator. 204251875Speter * Unlike ANSI/ISO C ctime(), apr_ctime() does not include 205266735Speter * a \\n at the end of the string. 206251875Speter * @param date_str String to write to. 207251875Speter * @param t the time to convert 208251875Speter */ 209251875SpeterAPR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t); 210251875Speter 211251875Speter/** 212266735Speter * Formats the exploded time according to the format specified 213251875Speter * @param s string to write to 214251875Speter * @param retsize The length of the returned string 215251875Speter * @param max The maximum length of the string 216251875Speter * @param format The format for the time string 217251875Speter * @param tm The time to convert 218251875Speter */ 219251875SpeterAPR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, 220251875Speter apr_size_t max, const char *format, 221251875Speter apr_time_exp_t *tm); 222251875Speter 223251875Speter/** 224251875Speter * Improve the clock resolution for the lifetime of the given pool. 225266735Speter * Generally this is only desirable on benchmarking and other very 226251875Speter * time-sensitive applications, and has no impact on most platforms. 227251875Speter * @param p The pool to associate the finer clock resolution 228251875Speter */ 229251875SpeterAPR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p); 230251875Speter 231251875Speter/** @} */ 232251875Speter 233251875Speter#ifdef __cplusplus 234251875Speter} 235251875Speter#endif 236251875Speter 237251875Speter#endif /* ! APR_TIME_H */ 238