KUTIL_EPOCH2STR(3) Library Functions Manual KUTIL_EPOCH2STR(3)

kutil_epoch2str, kutil_epoch2utcstr, KUTIL_EPOCH2TM, kutil_epoch2tmvals, kutil_date2epoch, kutil_date_check, kutil_datetime2epoch, kutil_datetime_check —
format and parse time for HTTP operations

library “libkcgi”

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.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);

int
kutil_date_check(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);

int
kutil_datetime_check(int64_t day, int64_t mon, int64_t year, int64_t hour, int64_t min, int64_t sec);

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 NUL 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() function 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). It does no validation of the given values. The kutil_datetime2epoch() function is similar, but acts upon time values as well.

The kutil_date2epoch() and kutil_datetime2epoch() functions have corresponding validation routines, kutil_date_check() and kutil_datetime_check(), which return zero if their arguments do not describe valid dates and times, and non-zero otherwise. Dates are constrained to be within years 1582 and 9999.

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.

These functions were written by Kristaps Dzonsons <kristaps@bsd.lv>.

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.
January 12, 2020 OpenBSD 6.5