timeradd(3bsd)

💖 timeradd — ok bestie, let's talk time structures 💖

So like… this is the timeradd(3bsd) page, from the BSD-flavoured corner of your system, and it's genuinely one of my faves because it's just ten little macros that do math on time and never once yells at you. 🌸

✨ NAME ✨

timeradd, timersub, timerclear, timerisset, timercmp, timespecadd, timespecsub, timespecclear, timespecisset, timespeccmp — operations on time structure 👑

📚 LIBRARY 📚

Utility functions from BSD systems — that's libbsd, and you link it with -lbsd. 🫶

🌈 SYNOPSIS 🌈

#include <sys/time.h>
(See libbsd(7) for include usage.)

void
timeradd(struct timeval *a, struct timeval *b, struct timeval *res);

void
timersub(struct timeval *a, struct timeval *b, struct timeval *res);

void
timerclear(struct timeval *tv);

int
timerisset(struct timeval *tv);

int
timercmp(struct timeval *a, struct timeval *b, CMP);

void
timespecadd(struct timespec *a, struct timespec *b,
    struct timespec *res);

void
timespecsub(struct timespec *a, struct timespec *b,
    struct timespec *res);

void
timespecclear(struct timespec *ts);

int
timespecisset(struct timespec *ts);

int
timespeccmp(struct timespec *a, struct timespec b, CMP);

lowkey important: the include line comes with a lil note attached — (See libbsd(7) for include usage.) — so go read that one too, bestie, it explains how the includes actually work here. 💅

💅 DESCRIPTION 💅

These are macros, not fancy functions, and they exist so you can mess with the timeval and timespec structures — the ones that get described over in timeval(3bsd). It's giving "tiny utility, enormous slay". ✨

• timeradd() and timespecadd() add the time info stored in a to b, and drop the result into res. With timeradd() the results get simplified so that the value of res->tv_usec is always less than 1,000,000 (that's 1 second, for the people in the back). With timespecadd() the res->tv_nsec member of struct timespec is always less than 1,000,000,000. Normalisation? Handled. You're welcome. 🎀
• timersub() and timespecsub() go the other way — they subtract the time info stored in b from a, and store the resulting structure in res. Math but make it cute. 🦋
• timerclear() and timespecclear() initialize the structures to midnight (0 hour) January 1st, 1970 — aka the Epoch. In other words, they set the members of the structure to zero. Clean slate, fresh start, new me energy. 💜
• timerisset() and timespecisset() return true if the input structure is set to any time value other than the Epoch. So like, "is this thing actually set or is it just zero" — that's the whole vibe check. ✅
• timercmp() and timespeccmp() compare a to b using the comparison operator you hand them in CMP, and the result of the comparison gets returned. You bring the operator, they bring the answer. 🤝

also real talk: peep that last synopsis signature — timespeccmp() takes struct timespec b, not a pointer, while its friends take pointers. That's not a typo on my end, that's literally what's written. Copy it exactly, bestie. 🙈

👀 SEE ALSO 👀

• timeval(3bsd)

🕰️ HISTORY 🕰️

The timeradd() family of macros first appeared in NetBSD 1.1. These were later ported to FreeBSD 2.2.6. The timespec() family of macros first appeared in NetBSD 1.2. Iconic lineage fr fr. 👑

and that's the whole page!! this one's from Debian, dated June 7, 2010 — so yeah, a lil vintage, but she still eats. mwah, go normalise your timevals responsibly 💖✨🎀