libapr's time APIs are almost based on POSIX scheme. The value of apr_time_t is the elapsed time since UNIX epoch time(1970/1/1). The big differences are that apr_time_t is 64bit(long long) number and it represents microseconds. The most useful API is apr_time_now(). As you can guess, it returns the current time. You can find the protype declaration in apr_time.h.
/* excerpted from apr_time.h */
APR_DECLARE(apr_time_t) apr_time_now(void);
In many cases, we need to convert apr_time_t value to the other formats. There are mainly two formats. - apr_time_exp_t (time structure) - string formats (e.g. rfc822)
We use the following APIs to convert apr_time_t to apr_time_exp_t structure.
/* excerpted from apr_time.h */
APR_DECLARE(apr_status_t) apr_time_exp_gmt(apr_time_exp_t *result, apr_time_t input);
APR_DECLARE(apr_status_t) apr_time_exp_lt(apr_time_exp_t *result, apr_time_t input);
The apr_time_exp_gmt() returns the result in GMT timezone, and apr_time_exp_lt() returns the result in local timezone. The first argument of both APIs is result argument.
We can do the opposite conversion. We use the following API to convert apr_time_exp_t structure to apr_time_t value.
/* excerpted from apr_time.h */
APR_DECLARE(apr_status_t) apr_time_exp_get(apr_time_t *result, apr_time_exp_t *input);
There are some APIs to convert apr_time_t to various string formats as follows:
/* excerpted from apr_time.h */
APR_DECLARE(apr_status_t) apr_rfc822_date(char *date_str, apr_time_t t);
APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t);
APR_DECLARE(apr_status_t) apr_strftime(char *s, apr_size_t *retsize, apr_size_t max, const char *format, apr_time_exp_t *tm);
On the other hand, if we convert such string formats to apr_time_t value, we have to call apr-util APIs, which are defined in apr_date.h.
Please take a look at time-sample.c about the usage of time APIs.
REMARK: As stated above, apr_time_t is long long type (64bit). Note that the following sample code causes overflow.
/* BUGGY sample. This overflows */
const apr_time_t ONE_HOUR = 1000 * 1000 * 60 * 60;
We can fix the bug by explicit type cast, but I recommend you to use implicit type cast which libapr provides. The following code shows it.
/* two examples to get around overflow above */
const apr_time_t ONE_HOUR = APR_TIME_C(1000) * 1000 * 60 * 60;
or
const apr_time_t ONE_HOUR = APR_USEC_PER_SEC * 60 * 60;
REMARK: Sometimes, often in debugging, we want to print out time values. Unfortunately, Unix and Windows have different printf(3) format specifier for 64bit value. On Unix it is "%lld" and on Windows it is "%I64d". For such portability issues, libapr provides format specifiers, e.g. APR_INT64_T_FMT. There is APR_TIME_T_FMT in apr_time.h. We can write portable code with such format specifiers.
/* On Unix, APR_INT64_T_FMT is defined in apr.h */
#define APR_INT64_T_FMT "lld"
/* On Windows, APR_INT64_T_FMT is defined in apr.h */
#define APR_INT64_T_FMT "I64d"
/* excerpted from apr_time.h */
#define APR_TIME_T_FMT APR_INT64_T_FMT
/* We can use APR_TIME_T_FMT as follows */
printf("The current time: %" APR_TIME_T_FMT "[us]\n", apr_time_now());