KUTIL_EPOCH2STR(3)

💖 NAME 💖

okay so welcome to the kutil_epoch2str(3) page, bestie — it lives in the Library Functions Manual, and it's the whole friend group of functions that format and parse time for HTTP operations: kutil_epoch2str, kutil_epoch2utcstr, KUTIL_EPOCH2TM, kutil_epoch2tmvals, kutil_date2epoch, kutil_date_check, kutil_datetime2epoch, and kutil_datetime_check. slay.

📚 LIBRARY 📚

the library is “libkcgi” — yes, that's the one, no cap.

🛠 SYNOPSIS 🛠

#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);

🌸 DESCRIPTION 🌸

kutil_epoch2str() takes an epoch value — literally seconds since Jan 1, 1970, 00:00:00 UTC — and formats it 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. heads up: 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. kutil_epoch2utcstr() is similar, conforming to ISO 8601, e.g., 2002-10-02T13:00:00Z. iconic.

the form kutil_epoch2tmvals() breaks down the epoch value like this:

• 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)
• 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.

kutil_date2epoch() converts a day, month, and year into an epoch (at time 00:00:00). it does no validation of the given values. kutil_datetime2epoch() is similar, but acts upon time values as well.

kutil_date2epoch() and kutil_datetime2epoch() 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. that's the scary part, bestie — do not ignore it.

👑 AUTHORS 👑

these 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.

mwah 💋 that's the whole page — source/version Debian, date $Mdocdate$, manual KUTIL_EPOCH2STR(3). periodt. 🫶