KUTIL_EPOCH2STR(3)

NAME
kutil_epoch2str, kutil_epoch2utcstr, KUTIL_EPOCH2TM, kutil_epoch2tmvals, kutil_date2epoch, kutil_datetime2epoch - format and parse time for HTTP operations

LIBRARY
libkcgi

SYNOPSIS
#include <stdarg.h>
#include <stdint.h>
#include <unistd.h>
#include <kcgi.h>
void
kutil_epoch2str(int64_t epoch, char *buf, size_t sz);
void
kutil_epoch2utcstr(int64_t epoch, char *buf, size_t sz);
KUTIL_EPOCH2TM(_tt, _tm)
void
kutil_epoch2tmvals(int64_t epoch, int *tm_sec, int *tm_min, int *tm_hour, int *tm_mday, int *tm_mon, int *tm_year, int *tm_wday, int *tm_yday);
int64_t
kutil_date2epoch(int64_t day, int64_t mon, int64_t year);
int64_t
kutil_datetime2epoch(int64_t day, int64_t mon, int64_t year, int64_t hour, int64_t min, int64_t sec);

DESCRIPTION
The kutil_epoch2str, function formats an epoch value (seconds since Jan 1, 1970, 00:00:00 UTC) into the buffer buf of size sz, which should be greater than or equal to 30 bytes for the date and trailing nil terminator. The format conforms to RFC 822, e.g., Wed, 02 Oct 2002 13:00:00 GMT. This will truncate all values before the zeroth epoch to zero (Jan 1 as given). This function is useful for properly setting date-time header values: KRESP_SET_COOKIE, KRESP_LAST_MODIFIED, KRESP_DATE, etc. The kutil_epoch2utcstr is similar, conforming to ISO 8601, e.g., 2002-10-02T13:00:00Z.

The form kutil_epoch2tmvals breaks down the epoch value as seconds 0–60 (tm_sec), minutes 0–59 (tm_min), hours 0–23 (tm_hour), day of month 1–31 (tm_mday), month 0–11 (tm_mon), year minus 1900, (tm_year), day of week with Sunday at 0 (tm_wday), and day of year 0–365 (tm_yday). If any of the pointer values are NULL, they are ignored. Negative input epoch values are bound to zero.

You can use the convenience KUTIL_EPOCH2TM macro to convert into struct tm, which is not provided directly to avoid pulling in the time.h header. The macro accepts an epoch and a struct tm, which the caller must have zeroed beforehand.

The kutil_date2epoch function converts a day, month, and year into an epoch (at time 00:00:00). If the year is before 1970 or any values are negative, this returns zero. The behaviour for invalid dates (e.g., a mon() value of 14) is undefined. The kutil_datetime2epoch is similar, but acts upon time values as well. The same rules regarding negative numbers and undefinedness apply.

All of these date functions are designed to avoid how native gmtime(3) and time formatting functions access time-zone files, which may unwittingly crash given some operating system's sandbox mechanisms.

AUTHORS
The kutil_epoch2str, kutil_epoch2utcstr, KUTIL_EPOCH2TM, kutil_epoch2tmvals, kutil_date2epoch, and kutil_datetime2epoch functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
The time_t and struct tm types are not used for the epoch to avoid expanding header requirements for <kcgi.h> and because the int64_t type is used consistently for integral values.