11.5. Time and Date Functions

Several API calls give you access to Apache's routines for formatting and parsing HTTP-compliant date strings. Also see the descriptions for ap_update_mtime( ) and ap_set_last_modified( ) in Section 10.6.4, under Section 10.6.4."

The declarations for these functions are scattered among several header files, including httpd.h, util_date.h, and http_request.h. In the following list we indicate where the function can be found:

char *ap_ht_time (pool *p, time_t t, const char *fmt, int gmt)

(Declared in the header file httpd.h.) Given a resource pool, a time_t timestamp, a character format, and a flag indicating whether or not to use GMT (Greenwich Mean Time, also known as Universal Standard Time), this function returns a character string containing the date. The character format uses the same code as the standard C library strftime() function, with the addition of two common extensions. The code %Z is substituted with the string GMT, and the code %z is substituted with +0000. See the manual page for strftime() for other codes you can use.

This example returns a string in the format Tue, 15 Sep 1998 14:36:31 GMT, which happens to be the HTTP date format recommended by RFCs 822 and 1123.

char *str = ap_ht_time(p, time(NULL), "%a %d %b %Y %T %Z", 0);

time_t ap_parseHTTPdate (const char *date)

(Declared in the header file util_date.c.) Given a char* containing a date in HTTP format, this routine parses the date and returns a time_t Unix timestamp. This routine is flexible enough to correctly handle minor variations in the date format, such as omitting the time zone and day of the week. Any text that follows the time string is ignored.

Here's an example of converting the incoming If-modified-since header into a timestamp. We then compare this timestamp to the requested file's last modification date and return HTTP_NOT_MODIFIED if the file is not newer than the browser's cached copy.

char *if_modified_since = ap_table_get(r->headers_in, "If-modified-since");
if (if_modified_since) {
   time_t secs = ap_parseHTTPdate(if_modified_since);
   if (secs <= r->mtime) {
      return HTTP_NOT_MODIFIED;
   }
}

See also ap_meets_conditions().

struct tm *ap_get_gmtoff (int *tz)

(Declared in the header file httpd.h.) The ap_get_gmtoff() function calculates the current local time and returns it as a tm* function result. The offset from GMT, in minutes, is returned in the tz argument.

Here's an example borrowed from mod_rewrite, which it uses to write logging timestamps in the format [14/Sep/1998:11:01:23 -0500].

static char *current_logtime(request_rec *r)
{
   int timz;
   struct tm *t;
   char tstr[80];
   char sign;

   t = ap_get_gmtoff(&timz);
   sign = (timz < 0 ? '-' : '+'),
   if (timz < 0) {
       timz = -timz;
   }

   strftime(tstr, 80, "[%d/%b/%Y:%H:%M:%S ", t);
   ap_snprintf(tstr + strlen(tstr), 80-strlen(tstr), "%c%.2d%.2d]",
               sign, timz/60, timz%60);
   return ap_pstrdup(r->pool, tstr);
}

char *ap_get_time (void)

(Declared in the header file httpd.h.) This function returns a date/time string in the format returned by the standard ctime() library call. Although this format is not compliant with the recommended HTTP header format, it is somewhat more concise and, for historical reasons, is used by the logging API for error log timestamps. Do not use it for the Expires header field or other HTTP headers that use dates. Use ap_gm_timestr_822() instead.

char *ctime_string = ap_get_time();

char *ap_gm_timestr_822 (pool *p, time_t sec)

(Declared in the header file httpd.h.) The unfortunately named function ap_gm_timestr_822() returns a date/time string that is formatted according to the RFC 822 SMTP specification. You can use this to create the outgoing Expires or Date fields. The sec argument contains the timestamp you wish to format.

In this example, we arrange for the outgoing document to expire 1 hour (3600 seconds) from the current time:

now = time(NULL);
ap_table_set(r->headers_out, "Expires", ap_gm_timestr_822(r->pool, now+3600))

time_t ap_tm2sec (const struct tm *t)

(Declared in the header file util_date.h.) The ap_tm2sec() function converts a GMT tm structure into a timestamp, the number of seconds since the start of the epoch. It is much faster than the standard equivalent mktime() function, and unlike mktime(), ap_tm2sec() will always return a valid time_t() value, which may be should an error occur.

time_t secs = ap_t2sec(&tm);