NAME
Util —
Some misc. helper functions that don't
need their own headers.
SYNOPSIS
#include
<Util.h>
unsigned long
UtilServerTs(void);
unsigned long
UtilLastModified(char
*);
int
UtilMkdir(const
char *, const
mode_t);
int
UtilSleepMillis(long);
size_t
UtilParseBytes(char
*);
ssize_t
UtilGetDelim(char
**, size_t *,
int,
FILE *);
ssize_t
UtilGetLine(char
**, size_t *,
FILE *);
DESCRIPTION
This header holds a number of random functions related to strings, time, and other tasks that don't require a full API, just one or two functions. For the most part, the functions here are entirely standalone, depending only on POSIX functions, however there are a few that specifically utilize Telodendria APIs. Those are noted.
UtilServerTs()
gets the current time in milliseconds since the Unix epoch. This uses
gettimeofday(2) and time_t, and converts it to a single
number, which is then returned to the caller. A note on the 2038 problem: as
long as sizeof(long) >= 8, that is, as long as the long datatype is 64
bits or more, which it is on all modern 64-bit Unix-like operating systems,
then everything should be fine. Expect Telodendria on 32 bit machines to
break in 2038. I didn't want to try to hack together some system to store
larger numbers than the architecture supports. We can always re-evaluate
things over the next decade.
UtilMkdir()
behaves just like the system call
mkdir(2), but it creates any intermediate directories if necessary,
unlike mkdir(2).
UtilSleepMillis()
sleeps the calling thread for the given number of milliseconds. It occurred
to me that POSIX does not specify a super friendly way to sleep, so this is
a wrapper around the POSIX
nanosleep(2) designed to make its usage much, much
simpler.
UtilLastModified()
uses stat(2) to get the last modified time of the given file. This is used
primarily for caching file data.
UtilParseBytes()
is a highly specialized function used in parsing the configuration file. It
takes in a string which is supposed to represent a number of bytes. It must
consist of an integer, followed by an optional suffix of k, K, m, M, g, or
G, indicating the value is kilobytes, megabytes, or gigabytes.
UtilGetDelim()
and
UtilGetLine()
work identically to the POSIX equivalents, documented in
getdelim(3), except it assumes pointers were allocated using the
Memory API, and it uses the Memory API itself to reallocate necessary
pointers.
RETURN VALUES
UtilServerTs() and
UtilLastModified() return timestamps in the form of
milliseconds since the Unix epoch as an unsigned long. The Matrix
specification requires timestamps be in milliseconds, so these functions are
designed to make that easy and convenient.
UtilMkdir() returns 0 on success, and -1
on failure, just like
mkdir(2). It also sets errno as appropriate.
UtilSleepMillis() returns the result of
calling
nanosleep(2).
UtilParseBytes() returns a number of
bytes, or 0 if there was an error parsing the byte string.
UtilGetDelim() and
UtilGetLine() return the same value as their POSIX
equivalents, documented in
getdelim(3).