forked from Telodendria/Telodendria
145 lines
4.8 KiB
Groff
145 lines
4.8 KiB
Groff
.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.
|