.Dd $Mdocdate: December 15 2022 $
.Dt UTIL 3
.Os Telodendria Project
.Sh NAME
.Nm Util
.Nd Some misc. helper functions that don't need their own headers.
.Sh SYNOPSIS
.In Util.h
.Ft unsigned long
.Fn UtilServerTs "void"
.Ft unsigned long
.Fn UtilLastModified "char *"
.Ft int
.Fn UtilMkdir "const char *" "const mode_t"
.Ft char *
.Fn UtilUtf8Encode "unsigned long"
.Ft char *
.Fn UtilStringDuplicate "char *"
.Ft char *
.Fn UtilStringConcat "char *" "char *"
.Ft int
.Fn UtilSleepMillis "long"
.Ft size_t
.Fn UtilParseBytes "char *"
.Ft ssize_t
.Fn UtilGetDelim "char **" "size_t *" "int" "FILE *"
.Ft ssize_t
.Fn UtilGetLine "char **" "size_t *" "FILE *"
.Ft char *
.Fn UtilRandomString "size_t"
.Sh DESCRIPTION
.Pp
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.
.Pp
.Fn UtilServerTs
gets the current time in milliseconds since the Unix epoch. This
uses
.Xr 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.
.Pp
.Fn UtilMkdir
behaves just like the system call
.Xr mkdir 2 ,
but it creates any intermediate directories if necessary, unlike
.Xr mkdir 2 .
.Pp
.Fn UtilUtf8Encode
takes a UTF-8 codepoint and encodes it into a string buffer
containing between 1 and 4 bytes. The string buffer is allocated
on the heap, so it should be freed when it is no longer needed.
.Pp
.Fn UtilStringDuplicate
duplicates a NULL-terminated string, and returns a new string on the
heap. This is useful when a function takes in a string that it needs
to store for for long amounts of time, even perhaps after the
original string is long gone.
.Pp
.Fn 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
.Xr nanosleep 2
designed to make its usage much, much simpler.
.Pp
.Fn UtilLastModified
uses
.Xr stat 2
to get the last modified time of the given file. This is used
primarily for caching file data.
.Pp
.Fn UtilStringConcat
takes in two NULL-terminated strings and returns their concatenation.
It works a lot like
.Xr strcat 3 ,
but it takes care of allocating memory big enough to hold both
strings. One or both strings may be NULL. If a string is NULL, it
is treated like an empty string.
.Pp
.Fn 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.
.Pp
.Fn UtilGetDelim
and
.Fn UtilGetLine
work identically to the POSIX equivalents, documented in
.Xr getdelim 3 ,
except it assumes pointers were allocated using the Memory API, and it
uses the Memory API itself to reallocate necessary pointers.
.Pp
.Fn UtilRandomString
generates a random string of the given length. At the moment, it only
selects from uppercase and lowercase numbers, but the character set may
be expanded in the future, or a function may be added to specify an
arbitrary character set.
.Sh RETURN VALUES
.Pp
.Fn UtilServerTs
and
.Fn 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.
.Pp
.Fn UtilMkdir
returns 0 on success, and -1 on failure, just like
.Xr mkdir 2 .
It also sets errno as appropriate.
.Pp
.Fn UtilSleepMillis
returns the result of calling
.Xr nanosleep 2 .
.Pp
.Fn UtilUtf8Encode ,
.Fn UtilStringDuplicate ,
and
.Fn UtilStringConcat
return a NULL-terminated string on the heap if they succeed, or NULL on failure.
Typically a failure in these functions indicate an error allocating memory.
.Pp
.Fn UtilParseBytes
returns a number of bytes, or 0 if there was an error parsing the byte string.
.Pp
.Fn UtilGetDelim
and
.Fn UtilGetLine
return the same value as their POSIX equivalents, documented in
.Xr getdelim 3 .
.Pp
.Fn UtilRandomString
returns a string, allocated on the heap, of the given length, or NULL if there
was an error allocating memory.