From a7c1ccd3f1ca76755b2f2f2f937b978f57c45568 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Wed, 15 Feb 2023 01:32:44 +0000 Subject: [PATCH] Update lots of documentation. --- TODO.txt | 7 ++++--- man/man3/Matrix.3 | 24 +----------------------- man/man3/Str.3 | 11 ++++++++++- man/man3/Util.3 | 46 +--------------------------------------------- site/index.html | 14 +++++++++++++- 5 files changed, 29 insertions(+), 73 deletions(-) diff --git a/TODO.txt b/TODO.txt index a7b14cb..989bc23 100644 --- a/TODO.txt +++ b/TODO.txt @@ -27,12 +27,13 @@ Milestone: v0.2.0 [x] Document MemoryHexDump() [x] Document DbExists() -[ ] Document UserInteractiveAuth (move docs from Matrix) [x] Document User -[ ] Move docs from Matrix to User for UserValidate -[ ] Document Str and remove old functions from Util docs. +[x] Document Str and remove old functions from Util docs. +[x] Move docs from Matrix to User for UserValidate +[ ] Document UserInteractiveAuth (move docs from Matrix) [ ] Clean up scripts (make tools/lib/matrix.sh) +[ ] Scripts to generate index with list of man pages and releases? [x] Update changelog [x] Fix man page links on website diff --git a/man/man3/Matrix.3 b/man/man3/Matrix.3 index d565389..b9a25ea 100644 --- a/man/man3/Matrix.3 +++ b/man/man3/Matrix.3 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: December 18 2022 $ +.Dd $Mdocdate: February 15 2023 $ .Dt MATRIX 3 .Os Telodendria Project .Sh NAME @@ -16,10 +16,6 @@ .Fn MatrixAuthenticate "HttpServerContext *" "Db *" .Ft HashMap * .Fn MatrixRateLimit "HttpServerContext *" "Db *" -.Ft int -.Fn MatrixUserValidate "char *" "char *" -.Ft int -.Fn MatrixHistoricalUserValidate "char *" "char *" .Sh DESCRIPTION .Nm provides some helper functions that bind to the @@ -104,18 +100,6 @@ user is authenticated. determines whether or not the request should be rate limited. It is expected that this will occur before most, if not all of the caller's logic. -.Pp -.Fn MatrixUserValidate -and -.Fn MatrixHistoricalUserValidate -take a Matrix ID local part and a domain name, in that order, and -check to see if it is valid according to the specification. -.Fn MatrixUserValidate -checks for a strictly spec-compliant user ID, but the specification -also requires historical usernames which do not meet the requirements -of the latest speck to also be supported, so -.Fn MatrixHistoricalUserValidate -can be used in cases where historical usernames may be dealt with. .Sh RETURN VALUES .Pp .Fn MatrixErrorCreate @@ -131,12 +115,6 @@ return NULL, then the caller can proceed assuming that all is well and no further action needs to be taken. If these functions do not return NULL, then the returned JSON object should be passed along to the client immediately without continuing. -.Pp -.Fn MatrixUserValidate -and -.Fn MatrixHistoricalUserValidate -return a boolean value, where 0 indicates the provided ID is -not valid, and non-zero values indicate the provided ID is valid. .Sh SEE ALSO .Xr HttpServer 3 , .Xr Log 3 , diff --git a/man/man3/Str.3 b/man/man3/Str.3 index 48efaff..61c1792 100644 --- a/man/man3/Str.3 +++ b/man/man3/Str.3 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: February 14 2023 $ +.Dd $Mdocdate: February 15 2023 $ .Dt STR 3 .Os Telodendria Project .Sh NAME @@ -43,4 +43,13 @@ strings may be NULL. If a string is NULL, it is treated like an empty string. .Fn StrRandom generates a random string of the specified length. .Sh RETURN VALUES +.Pp +.Fn StrUtf8Encode , +.Fn StrDuplicate , +.Fn StrConcat , +and +.Fn StrRandom +return a pointer to a NULL-terminated C string on the heap, or NULL if a memory +allocation error occurs. Returned pointers should be freed using the Memory API. .Sh SEE ALSO +.Xr Memory 3 diff --git a/man/man3/Util.3 b/man/man3/Util.3 index 8f55715..a9d4a37 100644 --- a/man/man3/Util.3 +++ b/man/man3/Util.3 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: December 15 2022 $ +.Dd $Mdocdate: February 15 2023 $ .Dt UTIL 3 .Os Telodendria Project .Sh NAME @@ -12,12 +12,6 @@ .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 @@ -26,8 +20,6 @@ .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, @@ -55,17 +47,6 @@ behaves just like the system call 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 @@ -79,14 +60,6 @@ uses 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. @@ -100,12 +73,6 @@ 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 @@ -124,13 +91,6 @@ It also sets errno as appropriate. 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 @@ -139,7 +99,3 @@ 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. diff --git a/site/index.html b/site/index.html index 5609372..fbdf38e 100644 --- a/site/index.html +++ b/site/index.html @@ -287,11 +287,23 @@ A simple implementation of the SHA2 hashing functions. A basic periodic job scheduler. + +User(3) + +Convenience functions for working with local users. + + + +Str(3) + +Functions for manipulating and creating strings. + +

-© 2022 Jordan Bancino <@jordan:bancino.net> +© 2023 Jordan Bancino <@jordan:bancino.net>
Updated on ${DATE}.