forked from Telodendria/Telodendria
101 lines
3.2 KiB
Groff
101 lines
3.2 KiB
Groff
.Dd $Mdocdate: February 15 2023 $
|
|
.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 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 *"
|
|
.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 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 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.
|
|
.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 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 .
|