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_pools.h" 27251875Speter#include "apr_errno.h" 28251875Speter 29251875Speter#ifdef __cplusplus 30251875Speterextern "C" { 31251875Speter#endif /* __cplusplus */ 32251875Speter 33251875Speter/** 34251875Speter * @defgroup apr_time Time Routines 35251875Speter * @ingroup APR 36251875Speter * @{ 37251875Speter */ 38251875Speter 39251875Speter/** month names */ 40251875SpeterAPR_DECLARE_DATA extern const char apr_month_snames[12][4]; 41251875Speter/** day names */ 42251875SpeterAPR_DECLARE_DATA extern const char apr_day_snames[7][4]; 43251875Speter 44251875Speter 45269847Speter/** number of microseconds since 00:00:00 January 1, 1970 UTC */ 46251875Spetertypedef apr_int64_t apr_time_t; 47251875Speter 48251875Speter 49251875Speter/** mechanism to properly type apr_time_t literals */ 50251875Speter#define APR_TIME_C(val) APR_INT64_C(val) 51251875Speter 52251875Speter/** mechanism to properly print apr_time_t values */ 53251875Speter#define APR_TIME_T_FMT APR_INT64_T_FMT 54251875Speter 55251875Speter/** intervals for I/O timeouts, in microseconds */ 56251875Spetertypedef apr_int64_t apr_interval_time_t; 57251875Speter/** short interval for I/O timeouts, in microseconds */ 58251875Spetertypedef apr_int32_t apr_short_interval_time_t; 59251875Speter 60251875Speter/** number of microseconds per second */ 61251875Speter#define APR_USEC_PER_SEC APR_TIME_C(1000000) 62251875Speter 63251875Speter/** @return apr_time_t as a second */ 64251875Speter#define apr_time_sec(time) ((time) / APR_USEC_PER_SEC) 65251875Speter 66251875Speter/** @return apr_time_t as a usec */ 67251875Speter#define apr_time_usec(time) ((time) % APR_USEC_PER_SEC) 68251875Speter 69251875Speter/** @return apr_time_t as a msec */ 70251875Speter#define apr_time_msec(time) (((time) / 1000) % 1000) 71251875Speter 72251875Speter/** @return apr_time_t as a msec */ 73251875Speter#define apr_time_as_msec(time) ((time) / 1000) 74251875Speter 75251875Speter/** @return milliseconds as an apr_time_t */ 76251875Speter#define apr_time_from_msec(msec) ((apr_time_t)(msec) * 1000) 77251875Speter 78251875Speter/** @return seconds as an apr_time_t */ 79251875Speter#define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC) 80251875Speter 81251875Speter/** @return a second and usec combination as an apr_time_t */ 82251875Speter#define apr_time_make(sec, usec) ((apr_time_t)(sec) * APR_USEC_PER_SEC \ 83251875Speter + (apr_time_t)(usec)) 84251875Speter 85251875Speter/** 86251875Speter * @return the current time 87251875Speter */ 88251875SpeterAPR_DECLARE(apr_time_t) apr_time_now(void); 89251875Speter 90251875Speter/** @see apr_time_exp_t */ 91251875Spetertypedef struct apr_time_exp_t apr_time_exp_t; 92251875Speter 93251875Speter/** 94251875Speter * a structure similar to ANSI struct tm with the following differences: 95251875Speter * - tm_usec isn't an ANSI field 96269847Speter * - tm_gmtoff isn't an ANSI field (it's a BSDism) 97251875Speter */ 98251875Speterstruct apr_time_exp_t { 99251875Speter /** microseconds past tm_sec */ 100251875Speter apr_int32_t tm_usec; 101251875Speter /** (0-61) seconds past tm_min */ 102251875Speter apr_int32_t tm_sec; 103251875Speter /** (0-59) minutes past tm_hour */ 104251875Speter apr_int32_t tm_min; 105251875Speter /** (0-23) hours past midnight */ 106251875Speter apr_int32_t tm_hour; 107251875Speter /** (1-31) day of the month */ 108251875Speter apr_int32_t tm_mday; 109251875Speter /** (0-11) month of the year */ 110251875Speter apr_int32_t tm_mon; 111251875Speter /** year since 1900 */ 112251875Speter apr_int32_t tm_year; 113269847Speter /** (0-6) days since Sunday */ 114251875Speter apr_int32_t tm_wday; 115269847Speter /** (0-365) days since January 1 */ 116251875Speter apr_int32_t tm_yday; 117251875Speter /** daylight saving time */ 118251875Speter apr_int32_t tm_isdst; 119251875Speter /** seconds east of UTC */ 120251875Speter apr_int32_t tm_gmtoff; 121251875Speter}; 122251875Speter 123251875Speter/** 124269847Speter * Convert an ansi time_t to an apr_time_t 125251875Speter * @param result the resulting apr_time_t 126251875Speter * @param input the time_t to convert 127251875Speter */ 128251875SpeterAPR_DECLARE(apr_status_t) apr_time_ansi_put(apr_time_t *result, 129251875Speter time_t input); 130251875Speter 131251875Speter/** 132269847Speter * Convert a time to its human readable components using an offset 133269847Speter * from GMT. 134251875Speter * @param result the exploded time 135251875Speter * @param input the time to explode 136251875Speter * @param offs the number of seconds offset to apply 137251875Speter */ 138251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_tz(apr_time_exp_t *result, 139251875Speter apr_time_t input, 140251875Speter apr_int32_t offs); 141251875Speter 142251875Speter/** 143269847Speter * Convert a time to its human readable components (GMT). 144251875Speter * @param result the exploded time 145251875Speter * @param input the time to explode 146251875Speter */ 147251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, 148251875Speter apr_time_t input); 149251875Speter 150251875Speter/** 151269847Speter * Convert a time to its human readable components in the local timezone. 152251875Speter * @param result the exploded time 153251875Speter * @param input the time to explode 154251875Speter */ 155251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, 156251875Speter apr_time_t input); 157251875Speter 158251875Speter/** 159269847Speter * Convert time value from human readable format to a numeric apr_time_t 160269847Speter * (elapsed microseconds since the epoch). 161251875Speter * @param result the resulting imploded time 162251875Speter * @param input the input exploded time 163251875Speter */ 164251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, 165251875Speter apr_time_exp_t *input); 166251875Speter 167251875Speter/** 168251875Speter * Convert time value from human readable format to a numeric apr_time_t that 169269847Speter * always represents GMT. 170251875Speter * @param result the resulting imploded time 171251875Speter * @param input the input exploded time 172251875Speter */ 173251875SpeterAPR_DECLARE(apr_status_t) apr_time_exp_gmt_get(apr_time_t *result, 174251875Speter apr_time_exp_t *input); 175251875Speter 176251875Speter/** 177251875Speter * Sleep for the specified number of micro-seconds. 178251875Speter * @param t desired amount of time to sleep. 179251875Speter * @warning May sleep for longer than the specified time. 180251875Speter */ 181251875SpeterAPR_DECLARE(void) apr_sleep(apr_interval_time_t t); 182251875Speter 183251875Speter/** length of a RFC822 Date */ 184251875Speter#define APR_RFC822_DATE_LEN (30) 185251875Speter/** 186251875Speter * apr_rfc822_date formats dates in the RFC822 187251875Speter * format in an efficient manner. It is a fixed length 188269847Speter * format which requires APR_RFC822_DATA_LEN bytes of storage, 189251875Speter * including the trailing NUL terminator. 190251875Speter * @param date_str String to write to. 191251875Speter * @param t the time to convert 192251875Speter */ 193251875SpeterAPR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t); 194251875Speter 195251875Speter/** length of a CTIME date */ 196251875Speter#define APR_CTIME_LEN (25) 197251875Speter/** 198251875Speter * apr_ctime formats dates in the ctime() format 199269847Speter * in an efficient manner. It is a fixed length format 200269847Speter * and requires APR_CTIME_LEN bytes of storage including 201251875Speter * the trailing NUL terminator. 202251875Speter * Unlike ANSI/ISO C ctime(), apr_ctime() does not include 203269847Speter * a \\n at the end of the string. 204251875Speter * @param date_str String to write to. 205251875Speter * @param t the time to convert 206251875Speter */ 207251875SpeterAPR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t); 208251875Speter 209251875Speter/** 210269847Speter * Formats the exploded time according to the format specified 211251875Speter * @param s string to write to 212251875Speter * @param retsize The length of the returned string 213251875Speter * @param max The maximum length of the string 214251875Speter * @param format The format for the time string 215251875Speter * @param tm The time to convert 216251875Speter */ 217251875SpeterAPR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, 218251875Speter apr_size_t max, const char *format, 219251875Speter apr_time_exp_t *tm); 220251875Speter 221251875Speter/** 222251875Speter * Improve the clock resolution for the lifetime of the given pool. 223269847Speter * Generally this is only desirable on benchmarking and other very 224251875Speter * time-sensitive applications, and has no impact on most platforms. 225251875Speter * @param p The pool to associate the finer clock resolution 226251875Speter */ 227251875SpeterAPR_DECLARE(void) apr_time_clock_hires(apr_pool_t *p); 228251875Speter 229251875Speter/** @} */ 230251875Speter 231251875Speter#ifdef __cplusplus 232251875Speter} 233251875Speter#endif 234251875Speter 235251875Speter#endif /* ! APR_TIME_H */ 236