diff options
author | sternenseemann <0rpkxez4ksa01gb3typccl0i@systemli.org> | 2020-08-25 13:22:02 +0200 |
---|---|---|
committer | sternenseemann <0rpkxez4ksa01gb3typccl0i@systemli.org> | 2020-08-25 13:23:13 +0200 |
commit | b50d7870ed25fbbe8533f3bb1311ea2b1307517a (patch) | |
tree | e6e2cc89470c0b457af22954c8640b9e97a70403 /timeutil.h | |
parent | 5c400e2a8f2277ebc7212422540a7b3085b7ef9d (diff) |
doc(timeutil): init docs for timeutil
Diffstat (limited to 'timeutil.h')
-rw-r--r-- | timeutil.h | 39 |
1 files changed, 35 insertions, 4 deletions
diff --git a/timeutil.h b/timeutil.h index 8ee39cc..7d0270e 100644 --- a/timeutil.h +++ b/timeutil.h @@ -1,12 +1,43 @@ +/*! + * @file + * @brief Utilities for rendering timestamps as strings + */ enum time_format { - RSS_TIME_FORMAT, - ATOM_TIME_FORMAT, - HTML_TIME_FORMAT_READABLE + RSS_TIME_FORMAT, //!< RFC822 formatted time with 4 instead of 2 year digits + ATOM_TIME_FORMAT, //!< RFC3339 formatted time + HTML_TIME_FORMAT_READABLE //!< like `ATOM_TIME_FORMAT`, but with space between date and time }; +/*! + * @brief Maximum size necessary to contain the output of flocaltime() + */ #define MAX_TIMESTR_SIZE 32 // max HTML/Atom: 24 + NUL byte // max RSS: 31 + NUL byte +/*! + * @brief Format given timestamp as a string in the local timezone + * + * flocaltime() is a wrapper around `strftime()` which supports + * a specific set of output formats. In contrast to `strftime()` + * it can output correct RFC3339 time strings and does localtime + * resolution for you. + * + * Example usage to print a RFC3339 formatted timestamp: + * + * ``` + * time_t some_time; + * char strtime[MAX_TIMESTR_SIZE]; + * + * if(flocaltime(strtime, ATOM_TIME_FORMAT, MAX_TIMESTR_SIZE, &some_time) > 0) { + * puts(strtime); + * } + * ``` + * + * @param b output buffer + * @param type time format to use for output + * @param size number of `char`s the buffer can hold + * @param time pointer to timestamp + * @return `0` on error, otherwise length of the string placed in `b` excluding terminating `NUL` byte + */ size_t flocaltime(char *b, enum time_format type, size_t size, const time_t *time); - |