From a08018870e47f32d666df9b81ccae3b19504a4fc Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 29 Apr 2023 18:47:20 +0000 Subject: [PATCH] Remove obsolete documentation. --- man/man3/Array.3 | 132 ------------------ man/man3/Base64.3 | 81 ----------- man/man3/CanonicalJson.3 | 69 --------- man/man3/Cron.3 | 96 ------------- man/man3/Db.3 | 121 ---------------- man/man3/HashMap.3 | 146 ------------------- man/man3/Http.3 | 186 ------------------------- man/man3/HttpServer.3 | 157 --------------------- man/man3/Json.3 | 263 ----------------------------------- man/man3/Log.3 | 155 --------------------- man/man3/Main.3 | 74 ---------- man/man3/Matrix.3 | 141 ------------------- man/man3/Memory.3 | 145 ------------------- man/man3/Queue.3 | 100 ------------- man/man3/Rand.3 | 44 ------ man/man3/Routes.3 | 87 ------------ man/man3/Sha2.3 | 27 ---- man/man3/Str.3 | 55 -------- man/man3/Telodendria.3 | 93 ------------- man/man3/TelodendriaConfig.3 | 95 ------------- man/man3/Uia.3 | 123 ---------------- man/man3/User.3 | 219 ----------------------------- man/man3/Util.3 | 101 -------------- 23 files changed, 2710 deletions(-) delete mode 100644 man/man3/Array.3 delete mode 100644 man/man3/Base64.3 delete mode 100644 man/man3/CanonicalJson.3 delete mode 100644 man/man3/Cron.3 delete mode 100644 man/man3/Db.3 delete mode 100644 man/man3/HashMap.3 delete mode 100644 man/man3/Http.3 delete mode 100644 man/man3/HttpServer.3 delete mode 100644 man/man3/Json.3 delete mode 100644 man/man3/Log.3 delete mode 100644 man/man3/Main.3 delete mode 100644 man/man3/Matrix.3 delete mode 100644 man/man3/Memory.3 delete mode 100644 man/man3/Queue.3 delete mode 100644 man/man3/Rand.3 delete mode 100644 man/man3/Routes.3 delete mode 100644 man/man3/Sha2.3 delete mode 100644 man/man3/Str.3 delete mode 100644 man/man3/Telodendria.3 delete mode 100644 man/man3/TelodendriaConfig.3 delete mode 100644 man/man3/Uia.3 delete mode 100644 man/man3/User.3 delete mode 100644 man/man3/Util.3 diff --git a/man/man3/Array.3 b/man/man3/Array.3 deleted file mode 100644 index 9205318..0000000 --- a/man/man3/Array.3 +++ /dev/null @@ -1,132 +0,0 @@ -.Dd $Mdocdate: November 24 2022 $ -.Dt ARRAY 3 -.Os Telodendria Project -.Sh NAME -.Nm Array -.Nd A simple dynamic array data structure. -.Sh SYNOPSIS -.In Array.h -.Ft Array * -.Fn ArrayCreate "void" -.Ft void -.Fn ArrayFree "Array *" -.Ft int -.Fn ArrayTrim "Array *" -.Ft size_t -.Fn ArraySize "Array *" -.Ft void * -.Fn ArrayGet "Array *" "size_t" -.Ft int -.Fn ArrayInsert "Array *" "void *" "size_t" -.Ft int -.Fn ArrayAdd "Array *" "void *" -.Ft void * -.Fn ArrayDelete "Array *" "size_t" -.Ft void -.Fn ArraySort "Array *" "int (*) (void *, void *)" -.Ft Array * -.Fn ArrayFromVarArgs "size_t" "va_list" -.Ft Array * -.Fn ArrayDuplicate "Array *" -.Sh DESCRIPTION -These functions implement a simple array data structure that -is automatically resized as necessary when new values are added. -This implementation does not actually store the values of the -items in it; it only stores pointers to the data. As such, you will -still have to manually maintain all your data. The advantage of this -is that these functions don't have to copy data, and thus don't care -how big the data is. Furthermore, arbitrary data can be stored in the -array. -.Pp -This array implementation is optimized for storage space and appending. -Deletions are expensive in that all the items of the list above a deletion -are moved down to fill the hole where the deletion occurred. Insertions are -also expensive in that all the elements above the given index must be shifted -up to make room for the new element. -.Pp -Due to these design choices, this array implementation is best suited to -linear writing, and then linear or random reading. -.Pp -These functions operate on an array structure which is opaque to the -caller. -.Pp -.Fn ArrayCreate -and -.Fn ArrayFree -allocate and deallocate an array, respectively. -Note that -.Fn ArrayFree -does not free any of the values stored in the array; it is the caller's -job to manage the memory for each item. Typically, the caller would -iterate over all the items in the array and free them before freeing -the array. -.Fn ArrayTrim -reduces the amount of unused memory by calling -.Xr realloc 3 -on the internal structure to perfectly fit the elements in the array. It -is intended to be used by functions that return relatively read-only arrays -that will be long-lived. -.Pp -.Fn ArrayInsert -and -.Fn ArrayDelete -are the main functions used to modify the array. -.Fn ArrayAdd -is a convenience method that simply appends a value to the end of the -array. It uses -.Fn ArrayInsert . -The array can also be sorted by using -.Fn ArraySort , -which takes a pointer to a function that compares elements. The function -should take two -.Dv void -pointers as parameters, and return an integer. The return value indicates -to the algorithm how the elements relate to each other. A return value of -0 indicates the elements are identical. A return value greater than 0 -indicates that the first item is "bigger" than the second item and should -thus appear after it in the array, and a value less than zero indicates -the opposite: the second element should appear after the first in the array. -.Pp -.Fn ArrayGet -is used to get the element at the specified index. -.Pp -.Fn ArrayFromVarArgs -is used to convert a variadic arguments list into an Array. In many -cases, the Array API is much easier to work with than -.Fn va_arg -and friends. -.Pp -.Fn ArrayDuplicate -duplicates an existing array. Note that Arrays only hold -pointers to data, not the data itself, so the duplicated array will -point to the same places in memory as the original array. -.Sh RETURN VALUES -.Fn ArrayCreate , -.Fn ArrayFromVarArgs , -and -.Fn ArrayDuplicate -return a pointer on the heap to a newly allocated array structure, or -.Dv NULL -if the allocation fails. -.Pp -.Fn ArrayGet -and -.Fn ArrayDelete -return pointers to values that were put into the array, or -.Dv NULL -if the provided array is -.Dv NULL -or the provided index was out of bounds. -.Fn ArrayDelete -returns the element at the specified index after removing it so that -it can be properly handled by the caller. -.Pp -.Fn ArrayTrim , -.Fn ArrayInsert , -and -.Fn ArrayAdd -return a boolean value indicating their status. They return a value of zero -on failure, and a non-zero value on success. -.Sh SEE ALSO -.Xr HashMap 3 , -.Xr Queue 3 diff --git a/man/man3/Base64.3 b/man/man3/Base64.3 deleted file mode 100644 index a424532..0000000 --- a/man/man3/Base64.3 +++ /dev/null @@ -1,81 +0,0 @@ -.Dd $Mdocdate: September 30 2022 $ -.Dt BASE64 3 -.Os Telodendria Project -.Sh NAME -.Nm Base64 -.Nd A simple base64 encoder/decoder with "unpadded base64" support. -.Sh SYNOPSIS -.In Base64.h -.Ft size_t -.Fn Base64EncodedSize "size_t" -.Ft size_t -.Fn Base64DecodedSize "const char *" "size_t" -.Ft char * -.Fn Base64Encode "const char *" "size_t" -.Ft char * -.Fn Base64Decode "const char *" "size_t" -.Ft void -.Fn Base64Unpad "char *" "size_t" -.Ft int -.Fn Base64Pad "char **" "size_t" -.Sh DESCRIPTION -This is an efficient yet simple base64 encoding and decoding -library that supports regular base64, as well as the Matrix -specification's extension to base64, called "unpadded base64." -.Nm provides the ability to convert between the two, instead of -just implementing "unpadded base64." -.Pp -.Fn Base64EncodedSize -and -.Fn Base64DecodedSize -compute the amount of characters needed to store an encoded or -decoded message, respectively. Both functions take the size of -the message being encoded or decoded, but -.Fn Base64DecodedSize -also takes a pointer to an encoded string, because a few bytes of -the string need to be read in order to compute the size. -.Pp -.Fn Base64Encode -and -.Fn Base64Decode -do the actual work of encoding and decoding base64 data. They both -take a string and its length. -.Pp -.Fn Base64Unpad -and -.Fn Base64Pad -are used to implement Matrix unpadded base64. -.Fn Base64Unpad -takes a valid base64 string and strips off the trailing equal signs, -as per the specification. -.Fn Base64Pad -does the opposite; it takes an unpadded base64 input string, and pads -it with equal signs as necessary, so that it can be properly decoded -with -.Fn Base64Decode -if necessary. However, the Matrix specification envisons unpadded base64 -as opaque; that is, once it's encoded, it never needs to be decoded. -In practice, a homeserver might need to decode an unpadded base64 string. -.Sh RETURN VALUES -.Fn Base64EncodedSize -and -.Fn Base64DecodedSize -simply return unsigned integers representing a number of bytes generated -from a simple computation. -.Pp -.Fn Base64Encode -and -.Fn Base64Decode -return pointers to new strings, allocated on the heap, or -.Dv NULL -if a heap allocation fails. These pointers must be -.Xr free 3 -ed -at some point when they are no longer needed. -.Pp -.Fn Base64Unpad -modifies the passed string in-place. It thus has no return value, because -it cannot fail. If the passed pointer is invalid, the behavior is undefined. -.Fn Base64Pad -returns a boolean value indicating whether the pad operation was successful. -In practice, this function will only fail if a bigger string is necessary, but -could not be automatically allocated on the heap. diff --git a/man/man3/CanonicalJson.3 b/man/man3/CanonicalJson.3 deleted file mode 100644 index 91fc44f..0000000 --- a/man/man3/CanonicalJson.3 +++ /dev/null @@ -1,69 +0,0 @@ -.Dd $Mdocdate: November 30 2022 $ -.Dt CANONICALJSON 3 -.Os Telodendria Project -.Sh NAME -.Nm CanonicalJson -.Nd An extension of JSON that produces the Matrix spec's "canonical" JSON. -.Sh SYNOPSIS -.In CanonicalJson.h -.Ft int -.Fn CanonicalJsonEncode "HashMap *" "FILE *" -.Ft char * -.Fn CanonicalJsonEncodeToString "HashMap *" -.Sh DESCRIPTION -.Pp -.Nm -is an extension of -.Xr Json 3 -that is specifically designed to produce the Matrix specification's -"canonical" JSON. -.Pp -Canonical JSON is defined as JSON that: -.Bl -bullet -offset indent -.It -Does not have any unecessary whitespace. -.It -Has all object keys lexicographically sorted. -.It -Does not contain any floating point numerical values. -.El -.Pp -The regular JSON encoder has no such rules, because normally they are -not needed. However, Canonical JSON is needed to consistently sign JSON -objects. -.Pp -.Fn CanonicalJsonEncode -encodes a JSON object following the rules of Canonical Json. See the -documentation for -.Fn JsonEncode , -documented in -.Xr Json 3 -for more details on how JSON encoding operates. This function exists -as an alternative to -.Fn JsonEncode , -but should not be preferred to it in most circumstances. It is a lot -more costly, as it must lexicographically sort all keys and strip out -float values. If at all possible, use -.Fn JsonEncode -because it is much cheaper both in terms of memory and CPU time. -.Pp -.Fn CanonicalJsonEncodeToString -encodes a JSON object to a string. -.Xr Json 3 -doesn't have any way to send JSON to a string, because there's -absolutely no reason to handle JSON strings in most cases. However, -the sole reason Canonical JSON exists is so that JSON objects can -be signed in a consistent way. Thus, you need a string to pass to -the signing function. -.Sh RETURN VALUES -.Pp -.Fn CanonicalJsonEncode -returns whether or not the JSON encoding operation was sucessful. -This function will fail only if NULL was given for any parameter. -Otherwise, if an invalid pointer is given, undefined behavior results. -.Pp -.Fn CanonicalJsonEncodeToString -returns a C string containing the canonical JSON representation of -the given object, or NULL if the encoding failed. -.Sh SEE ALSO -.Xr Json 3 diff --git a/man/man3/Cron.3 b/man/man3/Cron.3 deleted file mode 100644 index 96a36c0..0000000 --- a/man/man3/Cron.3 +++ /dev/null @@ -1,96 +0,0 @@ -.Dd $Mdocdate: December 24 2022 $ -.Dt CRON 3 -.Os Telodendria Project -.Sh NAME -.Nm Cron -.Nd Basic periodic job scheduler. -.Sh SYNOPSIS -.In Cron.h -.Ft Cron * -.Fn CronCreate "unsigned long" -.Ft void -.Fn CronOnce "Cron *" "void (*) (void *)" "void *" -.Ft void -.Fn CronEvery "Cron *" "unsigned long" "void (*) (void *)" "void *" -.Ft void -.Fn CronStart "Cron *" -.Ft void -.Fn CronStop "Cron *" -.Ft void -.Fn CronFree "Cron *" -.Sh DESCRIPTION -.Pp -.Nm -is an extremely basic job scheduler. So basic, in fact, -that it runs all jobs on a single thread, which means that it -is intended for short-lived jobs. In the future, -.Nm -might be extended to support a one-thread-per-job model, but -for now, jobs should consider that they are sharing their -thread, so they should not be long-running jobs. -.Pp -.Nm -works by "ticking" at an interval defined by the caller of -.Fn CronCreate . -At each tick, all the jobs are queried, and if they are due -to run again, their function is executed. As much as possible, -.Nm -tries to tick at constant intervals, however it is possible that -a job may overrun the tick duration. If this happens, -.Nm -ticks again immediately after all the jobs for the previous tick -have completed. This is in an effort to compensate for the lost -time, however it is important to note that when jobs overrun the -tick interval, the interval is pushed back. In this way, -.Nm -is best suited for scheduling jobs that should happen -"approximately" every so often; it is not a real-time scheduler -by any means. -.Pp -.Fn CronCreate -creates a new -.Nm -object that all the other functions use. Like most of the other -APIs in this project, it must be freed with -.Fn CronFree -when it is no longer needed. -.Pp -Jobs can be scheduled with -.Fn CronOnce -and -.Fn CronEvery . -.Fn CronOnce -schedules a one-off job to be executed only at the next tick, and -then discarded. This is useful for scheduling tasks that only have -to happen once, or very infrequently depending on conditions other -than the current time, but don't have to happen immediately. The -caller simply indicates that it wishes for the task to execute at -some time in the future. How far into the future this practically -ends up being is determined by how long it takes other jobs to -finish, and what the tick interval is. -.Pp -.Fn CronEvery -schedules a repetitive task to be executed at approximately the -given interval. As stated above, this is a fuzzy interval; depending -on the jobs being run and the tick interval, tasks may not happen -at exactly the scheduled time, but they will eventually happen. -.Pp -.Fn CronStart -and -.Fn CronStop -start and stop the ticking, respectively. -.Fn CronFree -discards all the job references and frees all memory associated -with the given instance of the -.Nm -instance. -.Sh RETURN VALUES -.Pp -.Fn CronCreate -returns a reference to a -.Nm , -or NULL if it was unable to allocate memory for it. -.Pp -The other functions in this header don't return anything. They -are assumed to usually work, unless their input is obviously -wrong. diff --git a/man/man3/Db.3 b/man/man3/Db.3 deleted file mode 100644 index 06dd8e7..0000000 --- a/man/man3/Db.3 +++ /dev/null @@ -1,121 +0,0 @@ -.Dd $Mdocdate: March 6 2023 $ -.Dt DB 3 -.Os Telodendria Project -.Sh NAME -.Nm Db -.Nd A minimal flat-file database with object locking and an efficient cache. -.Sh SYNOPSIS -.In Db.h -.Ft Db * -.Fn DbOpen "char *" "size_t" -.Ft void -.Fn DbClose "Db *" -.Ft DbRef * -.Fn DbCreate "Db *" "size_t" "..." -.Ft int -.Fn DbDelete "Db *" "size_t" "..." -.Ft DbRef * -.Fn DbLock "Db *" "size_t" "..." -.Ft int -.Fn DbUnlock "Db *" "DbRef *" -.Ft int -.Fn DbExists "Db *" "size_t" "..." -.Ft Array * -.Fn DbList "Db *" "size_t" "..." -.Ft void -.Fn DbListFree "Array *" -.Ft HashMap * -.Fn DbJson "DbRef *" -.Sh DESCRIPTION -.Pp -Telodendria operates on a flat-file database instead of a traditional relational -database. This greatly simplifies the persistent storage code, and creates a -relatively basic API, described by this page. -.Pp -.Fn DbOpen -and -.Fn DbClose -open and close a data directory. -.Fn DbOpen -takes the path to open, and a cache size in bytes. This API relies heavily on -caching, so the cache must be greater than the DB_MIN_CACHE preprocessor -constant. -.Pp -.Fn DbCreate -and -.Fn DbLock -load data objects from the database, with the notable difference being that -.Fn DbCreate -will fail if an object already exists, and -.Fn DbLock -will fail if an object does not exist. These are both variadic functions that -take a variable number of C strings, with the exact number being specified by -the second paramter. These C strings are used to generate a filesystem path from -which an object is loaded, unless it is already in the cache. -.Pp -Objects, when loaded, are locked both in memory and on disk, so that other threads -or processes cannot access them while they are locked. This is to ensure data -integrity. -.Pp -.Fn DbUnlock -unlocks an object and returns it back to the database, which syncs it to the -filesystem and caches it, if it isn't in the cache already. -.Pp -.Fn DbExists -checks the existence of the given database object in a more efficient -manner than attempting to lock it with -.Fn DbLock . -.Fn DbExists -does not lock the object, nor does it load it into memory if it exists. It -takes the same arguments as -.Fn DbLock -and -.Fn DbUnlock . -.Pp -.Fn DbJson -converts a database reference into JSON. At this time, the database actually -stores objects as JSON, so this just returns an internal pointer, but in the -future it may have to be generated by decompressing a binary blob, or something -of that nature. -.Pp -.Fn DbDelete -completely removes an object from the database. It purges it from both the -cache and the disk as soon as no more references to it are open. -.Pp -.Fn DbList -lists all of the objects at a given path. Unlike the other varargs -functions, it does not take a path to a specific object; it takes -a directory to be iterated. Note that the resulting list only contains -the objects in that directory, not subdirectories. -.Fn DbListFree -frees the list returned by this function. -.Sh RETURN VALUES -.Pp -.Fn DbOpen -returns a reference to a database pointer, or NULL if there was an error -allocating memory, or opening the given directory with the given cache size. -.Pp -.Fn DbCreate -and -.Fn DbLock -return a database reference, or NULL if there was an error obtaining a reference -to the specified object. -.Pp -.Fn DbUnlock -returns a boolean value indicating whether or not the reference was successfully -unlocked. If the unlock is successful, then a non-zero value is returned. If it -isn't, 0 is returned, and it is up to the caller to decide how to proceed. -.Pp -.Fn DbDelete -follows the same return value conventions as -.Fn DbUnlock ; -it reports the status of the deletion operation as a boolean value. -.Pp -.Fn DbList -returns an array of strings, or NULL if there was a memory or -filesystem error. -.Pp -.Fn DbJson -returns a JSON object. Consult -.Xr Json 3 -for the API used to manipulate this object. diff --git a/man/man3/HashMap.3 b/man/man3/HashMap.3 deleted file mode 100644 index 9aefe39..0000000 --- a/man/man3/HashMap.3 +++ /dev/null @@ -1,146 +0,0 @@ -.Dd $Mdocdate: October 11 2022 $ -.Dt HASHMAP 3 -.Os Telodendria Project -.Sh NAME -.Nm HashMap -.Nd A simple hash map implementation. -.Sh SYNOPSIS -.In HashMap.h -.Ft HashMap * -.Fn HashMapCreate "void" -.Ft void -.Fn HashMapFree "HashMap *" -.Ft void -.Fn HashMapLoadSet "HashMap *" "float" -.Ft void -.Fn HashMapFunctionSet "HashMap *" "unsigned long (*) (const char *)" -.Ft void * -.Fn HashMapSet "HashMap *" "char *" "void *" -.Ft void * -.Fn HashMapGet "HashMap *" "char *" -.Ft void * -.Fn HashMapDelete "HashMap *" "char *" -.Ft int -.Fn HashMapIterate "HashMap *" "char **" "void **" -.Sh DESCRIPTION -This is the public interface for Telodendria's hash map implementation. -This hash map is designed to be simple, well documented, and generally -readable and understandable, yet also performant enough to be useful, -because it is used extensively in Telodendria. -.Pp -Fundamentally, this is an entirely generic map implementation. It can -be used for many general purposes, but it is designed to only implement -the features that Telodendria needs to function well. One example of a -Telodendria-specific feature is that keys are -.Dv NULL -terminated -strings, not any arbitrary data. -.Pp -These functions operate on an opaque -.Dv HashMap -structure, which the caller has no knowledge about. -.Pp -.Fn HashMapCreate -creates a new hash map that is ready to be used with the rest of the -hash map functions. -.Fn HashMapFree -frees this hash map, such that it becomes invalid and any future use -with the functions in this API results in undefined behavior. Note that -it does not free the keys or values stored in the hash map, since this -implementation has no way of knowing what is actually stored in it, and -where it is located. You should use -.Fn HashMapIterate -to free the values appropriately. -.Pp -.Fn HashMapMaxLoadSet -controls the maximum load of the hash map before it is expanded. -When the hash map reaches the given capacity, it is grown. You don't -want to only grow hash maps when they are full, because that makes -them perform very poorly. The maximum load value is a percentage of how -full the hash map is, and it should be between 0 -and 1, where 0 means that no elements will cause the map to be expanded, -and 1 means that the hash map must be completely full before it is -expanded. The default maximum load on a new -.Dv HashMap -object is 0.75, which should be good enough for most purposes, but -if you need finer tuning, feel free to play with the max load with -this function. The changes take effect on the next insert. -.Pp -.Fn HashMapFunctionSet -allows the given hash map to use a custom hashing function. New hash -maps have a sane hashing function that should work okay for most use -cases, but if you have a better hash function, it can be specified with -this function. Do not change the hash function after keys have been -added; doing so results in undefined behavior. Only set the hash -function immediately after constructing a new hash map. -.Pp -.Fn HashMapSet -sets the given string key to the given value. Note neither the key nor the -value is copied into the hash map's own memory space; only pointers are -stored. It is the caller's job to ensure that the key and value memory -remains valid for the life of the HashMap, and are freed when they are no -longer needed. -.Fn HashMapGet -retrieves the value for the given key and .Fn HashMapDelete -removes a value from a given key. -.Pp -.Fn HashMapIterate -iterates over all the keys and values of a hash map. This function works -very similarly to -.Xr getopt 3 , -where calls are repeatedly made in a -.Dv while -loop until there are no more items to go over. The difference is that this -function does not rely on globals; it takes pointer pointers, and stores all -necessary state inside the hash map structure itself. Note that this does not -make this function thread-safe; two threads cannot be iterating over any given -hash map at the same time, though they can be iterating over different hash -maps at the same time. -.Pp -This function can be tricky to use in some scenarios, as it continues where -it left off on each call, until there are no more elements to go through in -the hash map. If you are not iterating over the entire map in one go, and -happen to break the loop, then the next time you attempt to iterate the -hash map, you'll start somewhere in the middle. Thus, it's recommended to -always iterate over the entire hash map if you're going to use this -function. Also note that the behavior of this function is undefined if -insertions or deletions occur during the iteration. It may work fine; it may -not. That functionality has not been tested. -.Pp -.Fn HashMapIterate -takes a pointer to a string ponter, and a pointer to a value pointer. When -iterating over the keys and values of the hash map, it sets these pointers -to the current position in the map so that the caller can use them for his -own purposes. -.Sh RETURN VALUES -.Fn HashMapCreate -may return -.Dv NULL -if memory could not be allocated on the heap. Otherwise, it returns a -valid pointer to a -.Dv HashMap -structure which can be used with the other functions in this API. -.Pp -.Fn HashMapSet -returns the previous value at the passed key, or -.Dv NULL -if no such value exists. All keys must have values; you can't set a key -to -.Dv NULL . -To delete a key, use the -.Fn HashMapDelete -function. -.Pp -.Fn HashMapDelete -returns the value that was deleted from the hash map at the given key, -or -.Dv NULL -if no such value exists. -.Pp -.Fn HashMapIterate -returns 1 if there are still elements left in the current iteration of the -hash map, or 0 if no valid hash map was provided, or there are no more elements -in it for the current iteration. Note that as soon as this function returns 0 -on a hash map, subsequent iterations will start from the beginning. -.Sh SEE ALSO -.Xr HashMap 3 , -.Xr Queue 3 diff --git a/man/man3/Http.3 b/man/man3/Http.3 deleted file mode 100644 index ff30642..0000000 --- a/man/man3/Http.3 +++ /dev/null @@ -1,186 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt HTTP 3 -.Os Telodendria Project -.Sh NAME -.Nm Http -.Nd Encode and decode various parts of the HTTP protocol. -.Sh SYNOPSIS -.In Http.h -.Ft const char * -.Fn HttpStatusToString "const HttpStatus" -.Ft HttpRequestMethod -.Fn HttpRequestMethodFromString "const char *" -.Ft const char * -.Fn HttpRequestMethodToString "const HttpRequestMethod" -.Ft char * -.Fn HttpUrlEncode "char *" -.Ft char * -.Fn HttpUrlDecode "char *" -.Ft HashMap * -.Fn HttpParamDecode "char *" -.Ft char * -.Fn HttpParamEncode "HashMap *" -.Ft HashMap * -.Fn HttpParseHeaders "FILE *" -.Sh DESCRIPTION -.Pp -.Nm -is a collection of utility functions that are useful for dealing with -HTTP. HTTP is not a complex protocol, but this API makes it a lot easier -to work with. -.Pp -.Fn HttpStatusToString -takes an HttpStatus and converts it into a string description of the -status, which is to be used in an HTTP response. For example, calling -.Fn HttpStatusToString "HTTP_GATEWAY_TIMEOUT" -produces the string "Gateway Timeout". -.Pp -HttpStatus is an enumeration that corresponds to the actual integer -values of the valid HTTP response codes. For example, calling -.Fn HttpStatusToString "504" -produces the same output. HttpStatus is defined as follows: -.Bd -literal -offset indent -typedef enum HttpStatus -{ - /* Informational responses */ - HTTP_CONTINUE = 100, - HTTP_SWITCHING_PROTOCOLS = 101, - HTTP_EARLY_HINTS = 103, - - /* Successful responses */ - HTTP_OK = 200, - HTTP_CREATED = 201, - HTTP_ACCEPTED = 202, - HTTP_NON_AUTHORITATIVE_INFORMATION = 203, - HTTP_NO_CONTENT = 204, - HTTP_RESET_CONTENT = 205, - HTTP_PARTIAL_CONTENT = 206, - - /* Redirection messages */ - HTTP_MULTIPLE_CHOICES = 300, - HTTP_MOVED_PERMANENTLY = 301, - HTTP_FOUND = 302, - HTTP_SEE_OTHER = 303, - HTTP_NOT_MODIFIED = 304, - HTTP_TEMPORARY_REDIRECT = 307, - HTTP_PERMANENT_REDIRECT = 308, - - /* Client error messages */ - HTTP_BAD_REQUEST = 400, - HTTP_UNAUTHORIZED = 401, - HTTP_FORBIDDEN = 403, - HTTP_NOT_FOUND = 404, - HTTP_METHOD_NOT_ALLOWED = 405, - HTTP_NOT_ACCEPTABLE = 406, - HTTP_PROXY_AUTH_REQUIRED = 407, - HTTP_REQUEST_TIMEOUT = 408, - HTTP_CONFLICT = 409, - HTTP_GONE = 410, - HTTP_LENGTH_REQUIRED = 411, - HTTP_PRECONDITION_FAILED = 412, - HTTP_PAYLOAD_TOO_LARGE = 413, - HTTP_URI_TOO_LONG = 414, - HTTP_UNSUPPORTED_MEDIA_TYPE = 415, - HTTP_RANGE_NOT_SATISFIABLE = 416, - HTTP_EXPECTATION_FAILED = 417, - HTTP_TEAPOT = 418, - HTTP_UPGRADE_REQUIRED = 426, - HTTP_PRECONDITION_REQUIRED = 428, - HTTP_TOO_MANY_REQUESTS = 429, - HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = 431, - HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = 451, - - /* Server error responses */ - HTTP_INTERNAL_SERVER_ERROR = 500, - HTTP_NOT_IMPLEMENTED = 501, - HTTP_BAD_GATEWAY = 502, - HTTP_SERVICE_UNAVAILABLE = 503, - HTTP_GATEWAY_TIMEOUT = 504, - HTTP_VERSION_NOT_SUPPORTED = 505, - HTTP_VARIANT_ALSO_NEGOTIATES = 506, - HTTP_NOT_EXTENDED = 510, - HTTP_NETWORK_AUTH_REQUIRED = 511 -} HttpStatus; -.Ed -.Pp -.Fn HttpRequestMethodFromString -and -.Fn HttpRequestMethodToString -convert an HttpRequestMethod enumeration value from and to a -string, respectively. The HttpRequestMethod enumeration is -defined as follows: -.Bd -literal -offset indent -typedef enum HttpRequestMethod -{ - HTTP_METHOD_UNKNOWN, - HTTP_GET, - HTTP_HEAD, - HTTP_POST, - HTTP_PUT, - HTTP_DELETE, - HTTP_CONNECT, - HTTP_OPTIONS, - HTTP_TRACE, - HTTP_PATCH -} HttpRequestMethod; -.Ed -.Pp -These can be used for parsing a request method and then storing -it efficiently; it doesn't have be stored as a string, and it's -much nicer to work with enumeration values than it is with -strings in C. The very first enumeration value is not to be -passed to -.Fn HttpRequestMethodToString , -rather it may be returned by -.Fn HttpRequestMethodFromString -if it cannot identify the request method string passed to it. -.Pp -.Fn HttpUrlEncode -and -.Fn HttpUrlDecode -deal with URL-safe strings. -.Fn HttpUrlEncode -encodes a C string such that it can appear in a URL, and -.Fn HttpUrlDecode -does the opposite; it decodes a URL string into the actual -bytes it is supposed to represent. -.Pp -.Fn HttpParamDecode -and -.Fn HttpParamEncode -convert HTTP parameters in the form of "param=value¶m2=val2" -to and from a hash map for easy parsing, manipulation, and encoding. -.Pp -.Fn HttpParseHeaders -reads HTTP headers from a stream and returns a hash map -of keys and values. All keys are lowercased to make -querying them consistent and not dependent on the casing -that was read from the stream. This is useful for both -client and server code, since the headers are of the same -format. This function should be used after parsing the -HTTP status line, because it does not parse that line. -It will stop when it encounters the first blank line, -which indicates that the body is beginning. After this -function completes, the body may be immediately be read -from the stream without any additional processing. -.Sh RETURN VALUES -.Pp -.Fn HttpStatusToString -and -.Fn HttpRequestMethodToString -both return constant strings; they are not to be manipulated because -doing so would result in a segmentation fault, as these strings -are stored in the data segment of the program. -.Pp -.Fn HttpUrlEncode , -.Fn HttpUrlDecode , -.Fn HttpParamDecode , -and -.Fn HttpParamEncode -all return strings that were allocated on the heap using the -Memory API, or NULL if there was an error allocating memory. -Thee strings returned can be manipulated at will, and must be -freed using the Memory API when they're no longer needed. -.Sh SEE ALSO -.Xr HashMap 3 , -.Xr Memory 3 diff --git a/man/man3/HttpServer.3 b/man/man3/HttpServer.3 deleted file mode 100644 index 0d48a14..0000000 --- a/man/man3/HttpServer.3 +++ /dev/null @@ -1,157 +0,0 @@ -.Dd $Mdocdate: December 13 2022 $ -.Dt HTTPSERVER 3 -.Os Telodendria Project -.Sh NAME -.Nm HttpServer -.Nd Extremely simple HTTP server. -.Sh SYNOPSIS -.In HttpServer.h -.Ft HttpServer * -.Fn HttpServerCreate "unsigned short" "unsigned int" "unsigned int" "HttpHandler *" "void *" -.Ft void -.Fn HttpServerFree "HttpServer *" -.Ft int -.Fn HttpServerStart "HttpServer *" -.Ft void -.Fn HttpServerJoin "HttpServer *" -.Ft void -.Fn HttpServerStop "HttpServer *" -.Ft HashMap * -.Fn HttpRequestHeaders "HttpServerContext *" -.Ft HttpRequestMethod -.Fn HttpRequestMethodGet "HttpServerContext *" -.Ft char * -.Fn HttpRequestPath "HttpServerContext *" -.Ft HashMap * -.Fn HttpRequestParams "HttpServerContext *" -.Ft char * -.Fn HttpResponseHeader "HttpServerContext *" "char *" "char *" -.Ft void -.Fn HttpResponseStatus "HttpServerContext *" HttpStatus" -.Ft FILE * -.Fn HttpStream "HttpServerContext *" -.Ft void -.Fn HttpSendHeaders "HttpServerContext *" -.Sh DESCRIPTION -.Nm -builds on the -.Xr Http 3 -API, and provides a very simple, yet very functional API for -creating an HTTP server. It aims at being easy to use and minimal, -yet also efficient. It uses non-blocking I/O, is fully multi-threaded, -very configurable, yet also able to be set up in just two function calls. -.Pp -This API should be familiar to those that have dealt with the HTTP server -libraries of other programming languages, particularly Java. In fact, -much of the terminology used in this code came from Java, and you'll -notice that the way responses are sent and received very closely resemble -the way it's done in Java. -.Pp -An HTTP server itself is created with -.Fn HttpServerCreate , -which takes the port number to create the server on, the number of threads to -use, the maximum number of connections, a request handler function, and the -arguments to that function, in that order. The request handler function is -of the following type: -.Bd -literal -offset indent -typedef void (HttpHandler) (HttpServerContext *, void *) -.Ed -.Pp -Where the void pointer received is the same pointer that was passed into -.Fn HttpServerCreate -as the last parameter. -.Pp -The returned HttpServer pointer is then managed by -.Fn HttpServerStart , -.Fn HttpServerStop , -.Fn HttpServerJoin , -and -.Fn HttpServerFree . -.Fn HttpServerStart -attempts to start the HTTP server, and returns immediately with the status. -This API is fully threaded and asyncronous, so the caller can continue working -while the HTTP server is running in a separate thread, and managing a pool -of threads to handle responses. Typically at some point after calling -.Fn HttpServerStart , -the program will have no more work to do, and so it will want to wait for -the HTTP server to finish. This is accomplished with -.Fn HttpServerJoin , -which joins the HTTP worker thread to the calling thread, making the -calling thread wait until the HTTP server has stopped. -.Pp -The only condition that will cause the HTTP server to stop is when -.Fn HttpServerStop -is invoked. This will typically happen in a signal handler that catches -signals instructing the program to shut down. Only after the server has -been stopped can it be freed with -.Fn HttpServerFree . -Note that calling -.Fn HttpServerFree -while the server is running results in undefined behavior. -.Pp -The remainder of the functions in this API are used inside of the -HTTP handler function passed by the caller of -.Fn HttpServerCreate . -They allow the handler to figure out the context of an HTTP request, -which includes the path that was requested, any parameters, and the -headers used to make the request. They also allow the handler -to respond with a status code, headers, and a body. -.Pp -.Fn HttpRequestHeaders , -.Fn HttpRequestMethodGet , -.Fn HttpRequestPath , -and -.Fn HttpRequestParams -get the information about the request. They should all be passed the -server context pointer that was passed into the handler function. -The data returned by these functions should be treated as read-only, -and should not be freed; their memory is handled outside of the HTTP -server handler function. -.Pp -.Fn HttpResponseHeader -and -.Fn HttpResponseStatus -are used to set response headers, and the response status of the -request, respectively. -.Pp -.Fn HttpStream -returns a stream that is both readable and writable. Reading from -the stream reads the request body that the client sent, if there is -one. Note that the request headers have already been read, so the stream -is correctly positioned at the beginning of the body of the request. -.Fn HttpSendHeaders -must be called before the stream is written to, otherwise a malformed -HTTP response will be sent. An HTTP handler should properly set all -the headers it intends to send, send those headers, and then write the -response body to the stream. Finally, note that the stream does not -need to be closed by the HTTP handler; in fact, doing so results in -undefined behavior. The stream is managed by the server itself. -.Sh RETURN VALUES -.Pp -.Fn HttpRequestHeaders -and -.Fn HttpRequestParams -return a hash map that can be used to access the request headers and -parameters, if necessary. Note that the request parameters would be -GET parameters, attached to the path that was requested. To get POST -parameters, read the stream returned by -.Fn HttpStream -and pass the contents into -.Fn HttpParamDecode -to get a hash map. -.Pp -.Fn HttpRequestPath -returns a string that represents the path that the client requested. Note -that it is not normalized; it is exactly what the client sent, so it should -be checked for path traversal attacks and other malformed paths that the -client may sent. -.Pp -.Fn HttpResponseHeader -returns the previous value of the given header, or NULL if there was no -previous value. -.Pp -.Fn HttpStream -returns a FILE pointer that can be read and written using the C standard -I/O functions. -.Sh SEE ALSO -.Xr Http 3 diff --git a/man/man3/Json.3 b/man/man3/Json.3 deleted file mode 100644 index 09989f4..0000000 --- a/man/man3/Json.3 +++ /dev/null @@ -1,263 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt JSON 3 -.Os Telodendria Project -.Sh NAME -.Nm Json -.Nd A fully-featured JSON API. -.Sh SYNOPSIS -.In Json.h -.Ft JsonType -.Fn JsonValueType "JsonValue *" -.Ft JsonValue * -.Fn JsonValueObject "HashMap *" -.Ft HashMap * -.Fn JsonValueAsObject "JsonValue *" -.Ft JsonValue * -.Fn JsonValueArray "Array *" -.Ft Array * -.Fn JsonValueAsArray " -.Ft JsonValue * -.Fn JsonValueString "char *" -.Ft char * -.Fn JsonValueAsString "JsonValue *" -.Ft JsonValue * -.Fn JsonValueInteger "long" -.Ft long -.Fn JsonValueAsInteger "JsonValue *" -.Ft JsonValue * -.Fn JsonValueFloat "double" -.Ft double -.Fn JsonValueAsFloat "JsonValue *" -.Ft JsonValue * -.Fn JsonValueBoolean "int" -.Ft int -.Fn JsonValueAsBoolean "JsonValue *" -.Ft JsonValue * -.Fn JsonValueNull "void" -.Ft void -.Fn JsonValueFree "JsonValue *" -.Ft void -.Fn JsonFree "HashMap *" -.Ft void -.Fn JsonEncodeString "const char *" "FILE *" -.Ft void -.Fn JsonEncodeValue "JsonValue *" "FILE *" "int" -.Ft int -.Fn JsonEncode "HashMap *" "FILE *" "int" -.Ft HashMap * -.Fn JsonDecode "FILE *" -.Ft JsonValue * -.Fn JsonGet "HashMap *" "size_t" "..." -.Ft JsonValue * -.Fn JsonSet "HashMap *" "size_t" "..." -.Sh DESCRIPTION -.Nm -is a fully-featured JSON API for C using -.Xr Array 3 -and -.Xr HashMap 3 -that can parse JSON, and serialize an in-memory structure -to JSON. -It builds on the foundation set up by those APIs because -that's all JSON really is, just maps and arrays. -.Nm -also provides a structure for encapsulating an arbitrary -value and identifying its type, making it easy for a program -to work with JSON data. -.Nm -is very strict and tries to adhere as closely as possible to -the proper defintion of JSON. It will fail on syntax errors -of any kind, which is fine for a Matrix homeserver because we can -just return M_BAD_JSON if anything here fails, but it may not -be suitable for other purposes. -.Pp -This JSON implementation focuses primarily on serialization and -deserialization to and from streams. It does not provide facilities -for handling JSON strings; it only writes JSON to output streams, and -reads them from input streams. If course, you can use the POSIX -.Xr fmemopen 3 -and -.Xr open_memstream 3 -if you want to deal with JSON strings, but JSON is intended to be an -exchange format. Data should be converted to JSON right before it is -leaving the program, and converted from JSON as soon as it is coming -in. -.Pp -The -.Nm -header defines the following enumeration for identifying types of -values: -.Bd -literal -offset indent -typedef enum JsonType -{ - JSON_NULL, /* Maps to C NULL */ - JSON_OBJECT, /* Maps to a HashMap of JsonValues */ - JSON_ARRAY, /* Maps to an Array of JsonValues */ - JSON_STRING, /* Maps to a NULL-terminated C string */ - JSON_INTEGER, /* Maps to a C long */ - JSON_FLOAT, /* Maps to a C double */ - JSON_BOOLEAN /* Maps to a C boolean, 1 or 0 */ -} JsonType; -.Ed -.Pp -A JsonValue encapsulates all the possible types that can be stored in -JSON. It is an opaque structure that can be managed entirely by the -functions defined in this API. It is important to note that in the case -of objects, arrays, and strings, this structure only stores pointers to -the allocated data, it doesn't store the data itself, but the data IS -freed when using -.Fn JsonFree . -.Pp -Objects are represented as hash maps consisting entirely of JsonValue -structures, and arrays are represented as arrays consisting entirely -of JsonValue structures. When generating a JSON object, any -attempt to stuff a value into a hash map or array without encoding it -as a JsonValue first will result in undefined behavior. -.Pp -.Fn JsonValueType -determines the type of a given JsonValue. -.Pp -The -.Fn JsonValue* -functions wrap their input in a JsonValue that represents the given -value. The -.Fn JsonValueAs* -functions do the opposite; they unwrap a JsonValue and return the -actual usable value itself. They all closely resemble each other and -they all behave the same way, so to save on time and effort, they're -not explicitly documented individually. If something is unclear about -how these functions work, consult the source code, and feel free -to write the documentation yourself for clarification. Otherwise, -reach out to the official Matrix rooms, and someone should be able -to help you. -.Pp -.Fn JsonValueNull -is a special case that represents a JSON null. Because -.Xr Array 3 -and -.Xr HashMap 3 -do not accept NULL values, this function should be used to represent -NULL in JSON. Even though a small amount of memory is allocated just -to point to NULL, this keeps the APIs clean. -.Pp -.Fn JsonValueFree -frees the memory being used by a JSON value. Note that this will -recursively free all Arrays, HashMaps, and other JsonValues that -are reachable from the given value. It also invokes -.Fn Free -(documented in -.Xr Memory ) -on all strings, so make sure passed string pointers point to strings -on the heap, not the stack. This will be the case for all strings -returned by -.Fn JsonDecode , -but if you are manually creating JSON objects and stitching them -together, you should be aware that calling this function on a value -that contains a pointer to a stack string will result in undefined -behavior. -.Pp -.Fn JsonFree -recursively frees a JSON object, iterating over all the values and -freeing them using -.Fn JsonValueFree . -.Pp -.Fn JsonEncodeString -encodes the given string in such a way that it can be embedded in a -JSON stream. This entails: -.Bl -bullet -offset indent -.It -Escaping quotes, backslashes, and other special characters using -their backslash escape. -.It -Encoding bytes that are not UTF-8 using escapes. -.It -Wrapping the entire string in double quotes. -.El -.Pp -This function is provided via the public -.Nm -API so that it is accessible to custom JSON encoders, such as -.Xr CanonicalJson 3 . -This will typically be used for encoding JSON keys; for encoding -values, just use -.Fn JsonEncodeValue . -.Pp -.Fn JsonEncodeValue -serializes a JsonValue as it would appear in JSON output. This is -a recursive function that also encodes all child values reachable -from the given value. This function is exposed via the public -.Nm -API so that it is accessible to custom JSON encoders. Normal users -that are not writing custom encoders should in most cases just use -.Fn JsonEncode -to encode an entire object. The third parameter is an integer that -represents the indent level of the value to be printed, or a negative -number if pretty-printing should be disabled, and JSON should be -printed as minimized as possible. If you want to pretty-print a -JSON object, set this to -.Va JSON_PRETTY . -To get the minified output, set it to -.Va JSON_DEFAULT . -.Pp -.Fn JsonEncode -encodes a JSON object as minimized JSON and writes it to the given -output stream. This function is recursive; it will serialize -everything accessible from the passed object. The third integer -parameter has the same behavior asa described above. -.Pp -.Fn JsonDecode -does the opposite of -.Fn JsonEncode ; -it reads from a JSON stream and decodes it into a hash map -of JsonValues. -.Pp -.Fn JsonSet -and -.Fn JsonGet -are convenience functions that allow the caller to retrieve and -manipulate arbitrarily deep keys within a JSON object. They take -a root JSON object, the number of levels deep to go, and then that -number of keys as a varargs list. All keys must have objects -as values, with the exception of the last one, which is the one -being retrieved or set. -.Fn JsonSet -will create any intermediate objects as necessary to set the -proper key. -.Sh RETURN VALUES -.Pp -.Fn JsonValueType -returns a JsonType, documented above, that tells what the given -value actually is, or JSON_NULL if the passed value is NULL. -Note that even a fully valid JsonValue may actually be of type -JSON_NULL, so this function should not be used to determine -whether or not a given value is valid. -.Pp -The -.Fn JsonValue* -functions return a JsonValue that holds a pointer to the passed -value, or NULL if there was an error allocating memory. The -.Fn JsonValueAs* -functions return the actual value represented by the given -JsonValue so that it can be manipulated by the program, or -NULL if no value was provided, or the value is not of the -correct type expected by the function. -.Pp -.Fn JsonEncode -returns whether or not the encoding operation was successful. -This function will fail if any passed parameters are NULL, -otherwise it will assume all pointers are valid and return a -success value. -.Pp -.Fn JsonDecode -returns a hash map of JsonValues that can be manipulated by -this API, or NULL if there was an error parsing the JSON. -.Pp -.Fn JsonGet -returns a JsonValue, or NULL if the requested key is not set -in the object. -.Fn JsonGet -returns the previous value of the provided key, or NULL if there -was no previous value. -.Sh SEE ALSO -.Xr HashMap 3 , -.Xr Array 3 diff --git a/man/man3/Log.3 b/man/man3/Log.3 deleted file mode 100644 index 19ee395..0000000 --- a/man/man3/Log.3 +++ /dev/null @@ -1,155 +0,0 @@ -.Dd $Mdocdate: February 15 2023 $ -.Dt LOG 3 -.Os Telodendria Project -.Sh NAME -.Nm Log -.Nd A simple logging framework for logging to files, standard output, or the system log. -.Sh SYNOPSIS -.In Log.h -.Ft LogConfig * -.Fn LogConfigCreate "void" -.Ft void -.Fn LogConfigFree "LogConfig *" -.Ft void -.Fn LogConfigLevelSet "LogConfig *" "int" -.Ft void -.Fn LogConfigIndent "LogConfig *" -.Ft void -.Fn LogConfigUnindent "LogConfig *" -.Ft void -.Fn LogConfigIndentSet "LogConfig *" "size_t" -.Ft void -.Fn LogConfigOutputSet "LogConfig *" "FILE *" -.Ft void -.Fn LogConfigFlagSet "LogConfig *" "int" -.Ft void -.Fn LogConfigFlagClear "LogConfig *" "int" -.Ft void -.Fn LogConfigTimeStampFormatSet "LogConfig *" "char *" -.Ft void -.Fn Log "LogConfig *" "int" "const char *" "..." -.Sh DESCRIPTION -.Pp -A heavily-modifed version of Shlog, a simple C logging library facility -that allows for colorful outputs, timestamps, and custom log levels. -This library differs from Shlog in that the naming conventions have -been updated to be consistent with Telodendria, and system log support -has been added. -.Pp -Shlog was originally a learning project. It worked well and produced -elegant logging output, so it was chosen to be the main logging -mechanism of Telodendria. The original Shlog project is now dead; Shlog -lives on now only as Telodendria's logging mechanism. -.Pp -One of the design choices made in this library, which unfortunately -makes code using it a little more verbose, is that multiple logging -configurations can exist in a program. No global variables are used, -and all functions are thread-safe. -.Pp -.Fn LogConfigCreate -creates a new log configuration with sane defaults that can be used -immediately. Note that every call to -.Fn Log -requires a valid configuration pointer. -.Fn LogConfigFree -frees all memory associated with that configuration, invalidating -it. Passing an invalid configuration pointer into any of the -functions defined here result in undefined behavior. The -.Fn LogConfig*Set -functions manipulate the data pointed to by the pointer returned -by -.Fn LogConfigCreate . -.Pp -.Fn LogConfigLevelSet -sets the current log level on the specified log configuration. This -indicates that only messages at or above this level should be -logged; all other messages are silently discarded by the -.Fn Log -function. The passed log level should be one of the log levels -defined by -.Xr syslog 3 . -Refer to that page for a complete list of acceptable log levels, -and note that passing in an invalid or unknown log level will -result in undefined behavior. -.Pp -.Fn LogConfigIndent -causes the output of -.Fn Log -to be indented two more spaces than it was previously. This can be -helpful when generating stack traces, or otherwise producing -hierarchical output. After calling this function, all future -messages using the given config will be indented two more spaces -than they were before. This is just a wrapper function around -.Fn LogConfigIndentSet , -which allows the caller to specify an arbitrary indentation in -spaces. -.Fn LogConfigUnindent -does the exact opposite of -.Fn LogConfigIndent ; -it subtracts two spaces from the indentation level, unless there -is no indent, then it does nothing. -.Pp -.Fn LogConfigOutputSet -sets the file stream that logging output should be written to. This -defaults to standard output, but it can be standard error, or some -other file stream. Passing a NULL value for the file pointer sets -the log output to standard output. Note that the output file stream -is only used if FLAG_OUTPUT_SYSLOG is not set. -.Pp -.Fn LogConfigFlagSet -and -.Fn LogConfigFlagClear -are used for setting a number of boolean options on a log -configuration. They utilize bitwise operators, so multiple options -can be set or cleared with a single function call using bitwise OR -operators. The flags defined as preprocessor macros, and are as -follows: -.Bl -tag -width Ds -.It LOG_FLAG_COLOR -When set, enable color-coded output on TTYs. Note that colors are -implemented as ANSI escape sequences, and are not written to file -streams that are not actually connected to a TTY, to prevent those -sequences from being written to a file. -.Xr isatty 3 -is checked before writing ANSI sequences. -.It LOG_FLAG_SYSLOG -When enabled, log output to the syslog using -.Xr syslog 3 , -instead of logging to the file set by -.Fn LogConfigOutputSet . -This flag always overrides the file stream set by that function, -regardless of when it was set. -.El -.Pp -.Fn LogConfigTimeStampFormatSet -allows a custom timestamp to be prepended to each message -if the output is not going to the system log. Consult your -system's documentation for -.Xr strftime 3 . -A value of NULL disables outputting a timestamp before messages. -.Pp -The -.Fn Log -function actually writes a log message to a console, file, system -log, or other supported output device using the given configuration. -This function is thread-safe; it locks a mutex before writing a -message, and then unlocks it after the message was written. Each -log configuration has its own mutex, so this function can be used -with mutiple active log configurations. -.Pp -This function only logs messages if their level is above or equal to -the currently configured log level, making it easy to turn some -messages on or off. The function has the same usage as -.Xr printf 3 . -.Sh RETURN VALUES -.Pp -.Fn LogConfigCreate -returns a pointer to a configuration structure on the heap, or NULL -if there was an error allocating memory for it. The returned -structure is opaque to the caller; the -.Fn LogConfig* -functions should be used to manipulate it. -.Pp -All other functions do not return anything. They are simply -assumed to always succeed. If any arguments are NULL, then the -functions do nothing, unless otherwise specifically noted. diff --git a/man/man3/Main.3 b/man/man3/Main.3 deleted file mode 100644 index ddd2d0f..0000000 --- a/man/man3/Main.3 +++ /dev/null @@ -1,74 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt MAIN 3 -.Os Telodendria Project -.Sh NAME -.Nm Main -.Nd Telodendria daemon entry function. -.Sh DESCRIPTION -.Pp -The -.Fn main -function is the first function that is executed. It is responsible -for setting things up and tearing them down. In order, it: -.Bl -bullet -.It -Creates a default logging configuration, installs the memory hook, -and prints the header. -.It -If running on OpenBSD, or is patched for other operating systems -that support it, executes -.Xr pledge 2 -with a minimal set of permissions for security. -.It -Parses the command line arguments and sets the relevant flags. -.It -If running on OpenBSD, or is patched for other operating systems -that support it, executes -.Xr unveil 2 -on the configuration file. -.It -parses and processes the configuration file. -.It -If running on OpenBSD, or is patched for other operating systems -that support it, executes -.Xr unveil 2 -on the data directory, and then disables all future calls to -.Xr unveil 2 . -.It -Applies all settings from the configuration file. -.It -Changes into the data directory. -.It -Binds the HTTP socket. -.It -If running as the root user and not on OpenBSD or other operating -systems that support -.Xr unveil 2 , -executes -.Xr chroot 2 -on the data directory. -.It -Detects the running user, and\(emif specified in the -configuration\(emdrops permissions. -.It -Sets up the database, and cron runner, then starts -the HTTP server and installs the signal handlers. -.It -Blocks on the HTTP server. -.It -Shuts down the HTTP server, cleans up all memory and -file handles, then exits. -.El -.Sh RETURN VALUE -.Pp -.Fn main -returns -.Va EXIT_SUCCESS -if everything runs correctly and Telodendria is -quit normally. It returns -.Va EXIT_FAILURE -if there was a fatal failure before the HTTP -server could be started. -.Pp -These values are returned to the operating system and -indicate the exit status of the process. diff --git a/man/man3/Matrix.3 b/man/man3/Matrix.3 deleted file mode 100644 index 0f71d54..0000000 --- a/man/man3/Matrix.3 +++ /dev/null @@ -1,141 +0,0 @@ -.Dd $Mdocdate: March 6 2023 $ -.Dt MATRIX 3 -.Os Telodendria Project -.Sh NAME -.Nm Matrix -.Nd Functions for writing Matrix API endpoints. -.Sh SYNOPSIS -.In Matrix.h -.Ft void -.Fn MatrixHttpHandler "HttpServerContext *" "void *" -.Ft void -.Fn MatrixErrorCreate "MatrixError" -.Ft HashMap * -.Fn MatrixRateLimit "HttpServerContext *" "Db *" -.Ft HashMap * -.Fn MatrixGetAccessToken "HttpServerContext *" "char **" -.Ft HashMap * -.Fn MatrixClientWellKnown "char *" "char *" -.Sh DESCRIPTION -.Nm -provides some helper functions that bind to the -.Xr HttpServer 3 -interface and add basic Matrix functionality, turning an -HTTP server into a Matrix homeserver. -.Pp -.Xr MatrixHttpHandler -is the HTTP handler function that handles all Matrix homeserver -functionality. It should be passed into -.Fn HttpServerCreate , -and it expects that an instance of MatrixHttpHandlerArgs will also -be provided, because that's what the void pointer is cast to. -That structure is defined as follows: -.Bd -literal -offset indent -typedef struct MatrixHttpHandlerArgs -{ - LogConfig *lc; - TelodendriaConfig *config; - Db *db; -} MatrixHttpHandlerArgs; -.Ed -.Pp -This structure should be populated once and then never modified again -for the duration of the HTTP server. -.Pp -.Fn MatrixErrorCreate -is a convenience function that constructs an error payload, including -the error code and message, given just a MatrixError. MatrixErrors -exactly follow the errors in the Matrix specification, and are -defined as follows: -.Bd -literal -offset indent -typedef enum MatrixError -{ - M_FORBIDDEN, - M_UNKNOWN_TOKEN, - M_MISSING_TOKEN, - M_BAD_JSON, - M_NOT_JSON, - M_NOT_FOUND, - M_LIMIT_EXCEEDED, - M_UNKNOWN, - M_UNRECOGNIZED, - M_UNAUTHORIZED, - M_USER_DEACTIVATED, - M_USER_IN_USE, - M_INVALID_USERNAME, - M_ROOM_IN_USE, - M_IVALID_ROOM_STATE, - M_THREEPID_IN_USE, - M_THREEPID_NOT_FOUND, - M_THREEPID_AUTH_FAILED, - M_THREEPID_DENIED, - M_SERVER_NOT_TRUSTED, - M_UNSUPPORTED_ROOM_VERSION, - M_BAD_STATE, - M_GUEST_ACCESS_FORBIDDEN, - M_CAPTCHA_NEEDED, - M_CAPTCHA_INVALID, - M_MISSING_PARAM, - M_INVALID_PARAM, - M_TOO_LARGE, - M_EXCLUSIVE, - M_RESOURCE_LIMIT_EXCEEDED, - M_CANNOT_LEAVE_SERVER_NOTICE_ROOM -} MatrixError; -.Ed -.Pp -.Fn MatrixRateLimit -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 MatrixGetAccessToken -reads the request headers and parameters, and attempts to obtain -the access token it found. The matrix specification says that an -access token can either be in an -.Dv Authorization -header, or in a -.Dv access_token -.Sy GET -paramter. This function checks both, and stores the access token -it finds in the passed character pointer. -.Pp -.Fn MatrixClientWellKnown -builds a client ``well-known'' JSON object, which contains -information about the homeserver base URL and identity server, -both of which should be provided by the caller in that order. This -object can be sent to a client as-is, as is the case with the -.Pa /.well-known/matrix/client -endpoint, or it can be added as a key in a response, as is the -case with a few endpoints. -.Sh RETURN VALUES -.Pp -.Fn MatrixErrorCreate -returns a JSON object that represents the given error code. It can be -immediately returned as the HTTP response body, or modified as needed. -.Pp -.Fn MatrixUserInteractiveAuth , -.Fn MatrixAuthenticate , -and -.Fn MatrixRateLimit -all return NULL when they are successful. That is, if these functions -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 MatrixGetAccessToken -returns a JSON object that should be immediately passed to the client -if it is not NULL. This JSON object holds an error message, indicating -that something went wrong. If this function does return NULL, then -the access token can be checked for validity. Otherwise, the access -token is either not valid or not provided so it should not be -checked. -.Pp -.Fn MatrixClientWellKnown -returns a JSON object, or NULL if something went wrong. -.Sh SEE ALSO -.Xr HttpServer 3 , -.Xr Log 3 , -.Xr TelodendriaConfig 3 , -.Xr Db 3 diff --git a/man/man3/Memory.3 b/man/man3/Memory.3 deleted file mode 100644 index 3033aae..0000000 --- a/man/man3/Memory.3 +++ /dev/null @@ -1,145 +0,0 @@ -.Dd $Mdocdate: January 9 2023 $ -.Dt MEMORY 3 -.Os Telodendria Project -.Sh NAME -.Nm Memory -.Nd Smart memory management. -.Sh SYNOPSIS -.In Memory.h -.Ft void * -.Fn MemoryAllocate "size_t" "const char *" "int" -.Ft void * -.Fn MemoryReallocate "void *" "size_t" "const char *" "int" -.Ft void -.Fn MemoryFree "void *" "const char *" "int" -.Ft size_t -.Fn MemoryAllocated "void" -.Ft void -.Fn MemoryFreeAll "void" -.Ft MemoryInfo * -.Fn MemoryInfoGet "void *" -.Ft size_t -.Fn MemoryInfoGetSize "MemoryInfo *" -.Ft const char * -.Fn MemoryInfoGetFile "MemoryInfo *" -.Ft int -.Fn MemoryInfoGetLine "MemoryInfo *" -.Ft void * -.Fn MemoryInfoGetPointer "MemoryInfo *" -.Ft void -.Fn MemoryIterate "void (*) (MemoryInfo *, void *)" "void *" -.Ft void -.Fn MemoryHook "void (*) (MemoryAction, MemoryInfo *, void *" "void *" -.Ft void -.Fn MemoryHexDump "MemoryInfo *" "void (*) (size_t, char *, char *, void *)" "void *" -.Sh DESCRIPTION -.Nm -is an API that allows for smart memory management and profiling. It wraps -the standard library functions -.Xr malloc 3 , -.Xr realloc 3 , -and -.Xr free 3 , -and offers identical semantics, while providing functionality that the -standard library doesn't have, such as getting statistics on the total -memory allocated on the heap, and getting the size of a block of memory -given a pointer. Additionally, thanks to preprocessor macros, the exact -file and line number at which an allocation, reallocation, or free occured -can be obtained given a pointer. Finally, all the blocks allocated on the -heap can be iterated and evaluated, and a callback function can be executed -every time a memory operation occurs. -.Pp -A number of macros are available, which make using the -.Nm -API much more useful. -.Fn Malloc -expands to -.Fn MemoryAllocate -with the __FILE__ and __LINE__ constants for the second and third -arguments respectively. Likewise, -.Fn Realloc -and -.Fn Free -expand to -.Fn MemoryReallocate -and -.Fn MemoryFree -with __FILE__ and __LINE__ as the second and third parameters. -This allows the API to be used exactly how the standard library -would be used. In fact, the functions which these macros expand to -are not intended to be called directly; only use the macros for the -best results. -.Pp -If all memory used in the program is managed by this API, there are some -helpful functions that allow the program to probe the state of the heap. -These functions are described here. -.Pp -.Fn MemoryAllocated -gets the total memory that the program has on the heap. This operation -iterates over all the heap allocations made with -.Fn MemoryAllocate -and then returns a total count, in bytes. -.Pp -.Fn MemoryFreeAll -iterates over all the heap allocations made with -.Fn MemoryAllocate -and calls -.Fn MemoryFree -on them. It immediately invalidates all pointers, and any subsequent -reads or writes to heap memory result in undefined behavior. This -is typically used at the end of the program. -.Pp -.Fn MemoryInfoGet -takes a pointer and fetches information about it, storing it in a -structure that can then be queried. -.Pp -.Fn MemoryInfoGetSize , -.Fn MemoryInfoGetFile , -.Fn MemoryInfoGetLine , -and -.Fn MemoryInfoGetPointer -all take in the structure returned by -.Fn MemoryInfoGet , -and return the respective property about the given property. These are -especially useful for logging and debugging with -.Fn MemoryIterate -and -.Fn MemoryHook . -.Pp -.Fn MemoryIterate -takes a pointer to a function that takes the memory information structure, -as well as a void pointer for caller-provided arguments. It iterates over -all the heap memory currently allocated at the time of calling. -.Fn MemoryHook -has a similar prototype, although the function pointer it takes is slightly -different. It also takes a memory action as the first argument. The -.Nm -API stores the pointer to this function, and executes it every time memory -is allocated, reallocated, or freed. This allows a program to execute code -whenever memory is allocated. -.Pp -.Fn MemoryHexDump -can be useful for debugging memory errors. It reads over a block of memory -and generates a hexadecimal and an ASCII string for each chunk of the block. -It takes a memory infomation structure and a callback function that processes -the offset, hexadecimal string, and ASCII string. This callback function -typically prints the strings out to a console, file, or other output -device. -.Sh RETURN VALUES -.Pp -.Fn MemoryAllocate -and -.Fn MemoryReallocate -return the same as their standard library counterparts. That is, a pointer -to memory on the heap, or NULL if there was an error allocating it. -.Pp -.Fn MemoryInfoGet -returns a pointer to information about a block on the heap, or NULL if the -passed pointer was not allocated by the -.Nm -API, or is no longer allocated. -.Pp -.Fn MemoryAllocated -returns an unsigned integer that indicates the number of bytes currently -allocated on the heap. - diff --git a/man/man3/Queue.3 b/man/man3/Queue.3 deleted file mode 100644 index 06ef194..0000000 --- a/man/man3/Queue.3 +++ /dev/null @@ -1,100 +0,0 @@ -.Dd $Mdocdate: November 25 2022 $ -.Dt QUEUE 3 -.Os Telodendria Project -.Sh NAME -.Nm Array -.Nd A simple static queue data structure. -.Sh SYNOPSIS -.In Queue.h -.Ft Queue * -.Fn QueueCreate "size_t" -.Ft void -.Fn QueueFree "Array *" -.Ft int -.Fn QueuePush "Queue *" "void *" -.Ft void * -.Fn QueuePop "Queue *" -.Ft void * -.Fn QueuePeek "Queue *" -.Ft int -.Fn QueueFull "Queue *" -.Ft int -.Fn QueueEmpty "Queue *" -.Sh DESCRIPTION -These functions implement a simple queue data structure that -is statically sized. -This implementation does not actually store the values of the -items in it; it only stores pointers to the data. As such, you will -still have to manually maintain all your data. The advantage of this -is that these functions don't have to copy data, and thus don't care -how big the data is. Furthermore, arbitrary data can be stored in the -queue. -.Pp -This queue implementation operates on the heap. It is a circular -queue, and it does not grow as it is used. Once the size is set, the -queue never gets any bigger. -.Pp -These functions operate on a queue structure which is opaque to the -caller. -.Pp -.Fn QueueCreate -and -.Fn QueueFree -allocate and deallocate a queue, respectively. -Note that -.Fn QueueFree -does not free any of the values stored in the queue; it is the caller's -job to manage the memory for each item. Typically, the caller would -dequeue all the items in the queue and free them before freeing -the queue itself. -.Pp -.Fn QueuePush -and -.Fn QueuePop -are the main functions used to modify the array. They enqueue and dequeue -elements from the queue structure, respectively. -.Pp -.Fn QueuePeek -simply returns the pointer that is next up in the queue without actually -discarding it, such that the next call to -.Fn QueuePeek -or -.Fn QueuePop -return the same pointer. -.Pp -.Fn QueueFull -and -.Fn QueueEmpty -return a boolean value that indicates whether or not the queue is full -or empty, respectively. -.Sh RETURN VALUES -.Pp -.Fn QueueCreate -returns a queue structure, or -.Dv NULL -if there was a memory allocation error. -.Pp -.Fn QueuePush -as well as -.Fn QueueFull -and -.Fn QueueEmpty -all return boolean values. In the case of -.Fn QueuePush -whether or not the push was actually successful is returned. This will -only happen if the queue is already full, or a -.Dv NULL -pointer is passed. -.Pp -.Fn QueuePop -and -.Fn QueuePeek -both return caller-managed pointers that would have been at some point -pushed into the queue with the -.Fn QueuePush -function. They may also return -.Dv NULL -if the queue is empty. -.Sh SEE ALSO -.Xr Array 3 , -.Xr HashMap 3 diff --git a/man/man3/Rand.3 b/man/man3/Rand.3 deleted file mode 100644 index 36e8b72..0000000 --- a/man/man3/Rand.3 +++ /dev/null @@ -1,44 +0,0 @@ -.Dd $Mdocdate: February 16 2023 $ -.Dt RAND 3 -.Os Telodendria Project -.Sh NAME -.Nm Rand -.Nd Thread-safe random numbers. -.Sh SYNOPSIS -.In Rand.h -.Ft int -.Fn RandInt "unsigned int" -.Ft void -.Fn RandIntN "int *" "size_t" "unsigned int" -.Sh DESCRIPTION -.Nm -is used for generating random numbers in a thread-safe way. Currently, -one seed is shared across all threads, which means only one thread can -generate random numbers at a time. In the future, a seed pool may be -maintained. The seed is initialized on the first call to a function -that needs it. It is initialized with the current timestamp, -the process ID, and the thread ID. These should be sufficiently random -sources, so the seed should be secure enough. -.Pp -.Fn RandInt -generates a single random integer between 0 and the passed value. -.Fn RandIntN -takes an integer pointer, a buffer size, and the maximum value a -random number is allowed to be. It generates the number of random -integers specified by the buffer size, and stores them at the passed -pointer. This allows a caller to get multiple random numbers at a -time, as each call to -.Fn RandInt -will have to lock and unlock a mutex, whereas -.Fn RandIntN -can obtain multiple random integers in a single pass. -.Sh RETURN VALUES -.Pp -.Fn RandInt -returns the value of -.Xr rand_r 3 -with the internally-stored seed. The return value should be in the -range of 0 to RAND_MAX. -.Sh SEE ALSO -.Xr Util 3 , -.Xr rand 3 diff --git a/man/man3/Routes.3 b/man/man3/Routes.3 deleted file mode 100644 index 3ad3a1c..0000000 --- a/man/man3/Routes.3 +++ /dev/null @@ -1,87 +0,0 @@ -.Dd $Mdocdate: December 12 2022 $ -.Dt ROUTES 3 -.Os Telodendria Project -.Sh NAME -.Nm Routes -.Nd Matrix API endpoint abstractions. -.Sh SYNOPSIS -.In Routes.h -.Ft char * -.Fn MATRIX_PATH_POP "MATRIX_PATH" -.Ft size_t -.Fn MATRIX_PATH_PARTS "MATRIX_PATH" -.Ft int -.Fn MATRIX_PATH_EQUALS "char *" "char *" -.Sh DESCRIPTION -.Pp -.Nm -provides all of the Matrix API route functions, as well as a few -helpful macros to be used to declare those route functions, and some -macros that are intended to be used inside them. -.Pp -The route macros are intended to increase the readability of the header, -so the individual routes are not documented here; only the helper -macros and structures are documented here. Consult the -.Pa Routes.h -file for a list of the registered route functions. -.Pp -.Fn MATRIX_PATH_POP -and -.Fn MATRIX_PATH_PARTS -are macros that abstract away the underlying data structure of the -path so that that routes don't have to care what it is. The reason -this design choice was made was so that the data structure can be -switched out without breaking all the routes. These macros should -be preferred to the actual underlying data structure functions, -because the data structure may change in the future. -.Pp -At the moment, the path data structure is just an array, but it would -be much more efficient to switch to a queue (which can be easily done -with the current Queue implementation if we just add a function that -computes how many elements are in the queue.) -.Pp -.Fn MATRIX_PATH_POP -returns the next available part of the path, and removes it from -the path such that the next call to -.Fn MATRIX_PATH_POP -returns the part after. -.Fn MATRIX_PATH_PARTS -returns the number of path parts remaining. -.Pp -.Fn MATRIX_PATH_EQUALS -is just a simple string comparison macro. It takes two strings and -returns a boolean value indicating whether or not they're equal. -.Pp -.Nm -also defines -.Fn ROUTE -and -.Fn ROUTE_IMPL . -.Fn ROUTE -is intended to be used only inside the route header, and should be -invoked to declare a new route function prototype. It takes the -route function name, which by convention starts with "Route". -.Fn ROUTE_IMPL -may be used to actually implement a route function. It takes the -route function name, and the name of the variable to put the -RouteArgs in. -.Pp -Every route function takes a RouteArgs structure, which is defined -as follows: -.Bd -literal -offset indent -typedef struct RouteArgs -{ - MatrixHttpHandlerArgs *matrixArgs; - HttpServerContext *context; - MATRIX_PATH *path; -} RouteArgs; -.Ed -.Sh RETURN VALUES -.Pp -Each route returns a JSON hash map that contains the response it -intends to return to the client making the request. Routes -should NOT return NULL, because then no body will be returned to -the client, and that is almost always a bug. The Matrix specification -usually mandates that at least an empty JSON object is returned. -.Sh SEE ALSO -.Xr Matrix 3 diff --git a/man/man3/Sha2.3 b/man/man3/Sha2.3 deleted file mode 100644 index adb3bbc..0000000 --- a/man/man3/Sha2.3 +++ /dev/null @@ -1,27 +0,0 @@ -.Dd $Mdocdate: December 19 2022 $ -.Dt SHA2 3 -.Os Telodendria Project -.Sh NAME -.Nm Sha2 -.Nd A simple implementation of the SHA2 hashing functions. -.Sh SYNOPSIS -.In Sha2.h -.Ft char * -.Fn Sha256 "char *" -.Sh DESCRIPTION -.Pp -This API defines simple functions for computing SHA2 hashes. At the -moment, it only defines -.Fn Sha256 , -which computes the SHA-256 hash of the given C string. It is not trivial -to implement SHA-512 in ANSI C due to the lack of a 64-bit integer -type, so that hash function has been omitted. -.Sh RETURN VALUES -.Pp -.Fn Sha256 -returns a string allocated on the heap using the Memory API, or NULL -if there was an error allocating memory for it. The returned string -should be freed when it is no longer needed. -.Sh SEE ALSO -.Xr Memory 3 , -.Xr Base64 3 diff --git a/man/man3/Str.3 b/man/man3/Str.3 deleted file mode 100644 index 61c1792..0000000 --- a/man/man3/Str.3 +++ /dev/null @@ -1,55 +0,0 @@ -.Dd $Mdocdate: February 15 2023 $ -.Dt STR 3 -.Os Telodendria Project -.Sh NAME -.Nm Str -.Nd Functions for manipulating and creating strings. -.Sh SYNOPSIS -.In Str.h -.Ft char * -.Fn StrUtf8Encode "unsigned long" -.Ft char * -.Fn StrDuplicate "const char *" -.Ft char * -.Fn StrConcat "size_t" "..." -.Ft char * -.Fn StrRandom "size_t" -.Sh DESCRIPTION -.Nm -provides string-related functions. It is called -.Nm , -not String, because some platforms (Windows) do not have -case-sensitive filesystems, so String and string are the same thing, which poses -a problem because string is a standard library header. -.Pp -.Fn StrUtf8Encode -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 StrDuplicate -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 long amounts -of time, even perhaps after the original string is gone. -.Pp -.Fn StrConcat -is a var-args function that takes the number of NULL-terminated strings specified -by the first argument, and returns a new string that contains their concatenation. -It works a lot like -.Xr strcat 3 , -but it takes care of allocating memory big enough to hold all the strings. Any -strings may be NULL. If a string is NULL, it is treated like an empty string. -.Pp -.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/Telodendria.3 b/man/man3/Telodendria.3 deleted file mode 100644 index 9711122..0000000 --- a/man/man3/Telodendria.3 +++ /dev/null @@ -1,93 +0,0 @@ -.Dd $Mdocdate: March 12 2023 $ -.Dt TELODENDRIA 3 -.Os Telodendria Project -.Sh NAME -.Nm Telodendria -.Nd Branding and callback functions specific to Telodendria. -.Sh SYNOPSIS -.In Telodendria.h -.Vt const char -.Va TelodendriaLogo[][] -.Pp -.Vt const char -.Va TelodendriaHeader[][] -.Pp -.Ft void -.Fn TelodendriaHexDump "size_t" "char *" "char *" "void *" -.Ft void -.Fn TelodendriaMemoryHook "MemoryAction" "MemoryInfo *" "void *" -.Ft void -.Fn TelodendriaMemoryIterator "MemoryInfo *" "void *" -.Ft void -.Fn TelodendriaPrintHeader "LogConfig *" -.Sh DESCRIPTION -.Pp -This API provides the callbacks used to hook Telodendria into -the various other APIs. It exists primarily to be called by -.Fn main , -but these functions are not static so that -.Fn -main can be in a separate compilation unit. -.Pp -.Va TelodendriaLogo -and -.Va TelodendriaHeader -are -.Va TELODENDRIA_LOGO_HEIGHT -by -.Va TELODENDRIA_LOGO_WIDTH -and -.Va TELODENDRIA_HEADER_HEIGHT -by -.Va TELODENDRIA_HEADER_WIDTH -character arrays, respectively. They hold C strings that -are used to generate the logo and header. -.Sy NOTE: -the Telodendria logo belong solely to the Telodendria -project. If this code is modified and distributed as a -package other than the official Telodendria source -package, the logo must be replaced with a different -one, or removed entirely. Consult the license section -of -.Xr Telodendria 7 -for details. -.Pp -.Fn TelodendriaHexDump -follows the function prototype required by the -.Fn MemoryHexDump -function, documented in -.Xr Memory 3 . -This function is responsible for outputting memory -hex dumps to the log. -Its fourth parameter is cast to a LogConfig object, -so one should be passed into the -.Fn MemoryHexDump -function. -.Pp -.Fn TelodendriaMemoryIterator -follows the function prototype required by the -.Fn MemoryIterate -function, documented in -.Xr Memory 3 . -This function is executed at the end of the program's -execution and detects leaks that occurred during normal -operation. -.Pp -.Fn TelodendriaMemoryHook -follows the function prototype required by the -.Fn MemoryHook -function, documented in -.Xr Memory 3 . -This function is executed every time an allocation, -re-allocation, or free occurs, and is responsible for -logging memory operations to the log. -.Pp -.Fn TelodendriaPrintHeader -prints the logo and header, along with the copyright -year and holder, and version number out to the log. -.Sh RETURN VALUES -.Pp -None of the functions in this API return anything. -.Sh SEE ALSO -.Xr Memory 3 , -.Xr Log 3 diff --git a/man/man3/TelodendriaConfig.3 b/man/man3/TelodendriaConfig.3 deleted file mode 100644 index 02d46cf..0000000 --- a/man/man3/TelodendriaConfig.3 +++ /dev/null @@ -1,95 +0,0 @@ -.Dd $Mdocdate: December 10 2022 $ -.Dt TELODENDRIACONFIG 3 -.Os Telodendria Project -.Sh NAME -.Nm TelodendriaConfig -.Nd Parse the configuration file into a structure. -.Sh SYNOPSIS -.In TelodendriaConfig.h -.Ft TelodendriaConfig * -.Fn TelodendriaConfigParse "HashMap *" "LogConfig *" -.Ft void -.Fn TelodendriaConfigFree "TelodendriaConfig *" -.Sh DESCRIPTION -.Pp -Validate and maintain the Telodendria server's configuration data. This API -builds on the JSON API to add Telodendria-specific parsing. It takes a -fully-parsed JSON object and converts it into a TelodendriaConfig, which is -much more structured and easier to work with than the JSON. The config -structure is not opaque like many other structures in Telodendria. This is -intentional; defining functions for all of the fields would just add a lot -of unecessary overhead. The structure is defined as follows: -.Bd -literal -offset indent -typedef struct TelodendriaConfig -{ - char *serverName; - char *baseUrl; - char *identityServer; - - char *uid; - char *gid; - char *dataDir; - - unsigned short listenPort; - unsigned int flags; - unsigned int threads; - unsigned int maxConnections; - - size_t maxCache; - - char *logTimestamp; - int logLevel; -} TelodendriaConfig; -.Ed -.Pp -Since the configuration will live in memory for a long time, it is important -that unused values are freed as soon as possible. Therefore, the Telodendria -structure is not opaque; values are accessed directly, and they can be -freed as the program wishes. Do note that if you're going to free a value, you -should set it to NULL, because -.Fn TelodendriaConfigFree -will unconditionally call -.Fn Free -on all values. -.Pp -The flags variable in this structure is a bit field that contains the OR-ed values -of any of the given flags: -.Bd -literal -offset indent -typedef enum TelodendriaConfigFlag -{ - TELODENDRIA_FEDERATION, - TELODENDRIA_REGISTRATION, - - TELODENDRIA_LOG_COLOR, - - TELODENDRIA_LOG_FILE, - TELODENDRIA_LOG_STDOUT, - TELODENDRIA_LOG_SYSLOG -} TelodendriaConfigFlag; -.Ed -.Pp -Do note that the actual values of these enums are omitted, but they can be -OR-ed together and added to flags. -.Pp -.Fn TelodendriaConfigParse -parses a JSON map, extracting the necessary values, validating them, and then -adding them to a new TelodendriaConfig for future use by the program. All values -are copied, so the JSON hash map can be safely freed if this function -succeeds. It takes a working log configuration so that messages can be written -to the log as the parsing progresses, to warn users about default values and -report errors, for example. -.Pp -.Fn TelodendriaConfigFree -frees all of the memory allocated for the given configuration. This function -unconditionally calls -.Fn Free -on all items in the structure, so make sure that items that were already freed -are NULL. -.Sh RETURN VALUES -.Pp -.Fn TelodendriaConfigParse -returns a TelodendriaConfig that is completely independent of the passed -configuration hash map, or NULL if one or more required values is missing, or -there was some other error while parsing the configuration. -.Sh SEE ALSO -.Xr Json 3 diff --git a/man/man3/Uia.3 b/man/man3/Uia.3 deleted file mode 100644 index 4c303a8..0000000 --- a/man/man3/Uia.3 +++ /dev/null @@ -1,123 +0,0 @@ -.Dd $Mdocdate: March 7 2023 $ -.Dt UIA 3 -.Os Telodendria Project -.Sh NAME -.Nm Uia -.Nd User Interactive Authentication API. -.Sh SYNOPSIS -.In Uia.h -.Ft UiaStage * -.Fn UiaStageBuild "char *" "HashMap *" -.Ft Array * -.Fn UiaDummyFlow "void" -.Ft void -.Fn UiaCleanup "MatrixHttpHandlerArgs *" -.Ft int -.Fn UiaComplete "Array *" "HttpServerContext *" "Db *" "HashMap *" "HashMap **" "TelodendriaConfig *" -.Ft void -.Fn UiaFlowsFree "Array *" -.Sh DESCRIPTION -.Nm -takes care of all the logic for performing user interactive -authentication as defined by the Matrix specification. API endpoints -that require authentication via user interactive authentication -build up flows and any necessary parameters, and pass them into -.Fn UiaComplete , -which validates -.Dv auth -objects and maintains session state to track the progress of a -client through the user interactive authentication flows. The idea -is that an API endpoint will not progress until user interactive -authentication has succeeded. -.Nm -makes it easy for the numerous API endpoints that utilize this -authentication mechanism to implement it. -.Pp -.Fn UiaStageBuild -builds a single stage. A stage consists of a string identifying its -type, which is used to instruct the client as to what should be -done, and parameters, which is a JSON object that contains -implementation-specific parameters for completing the stage. This -function takes those two parameters in that order. -.Pp -.Fn UiaDummyFlow -builds a flow that consists only of a dummy stage. This is useful -when an endpoint is required to use user interactive authentication, -but doesn't actually want to require the user to do anything. Since -the dummy flow is a pretty common flow, it seemed sensible to have -a function for it. Other flows are built by the caller that wishes -to perform user interactive authentication. -.Pp -.Fn UiaCleanup -should be called periodically to purge old sessions. Session are -only valid for a few minutes after their last access. After that, they -should be purged so the database doesn't fill up with session files. -This function is specifically designed to be called via -.Xr Cron 3 . -.Pp -.Fn UiaComplete -does the bulk of the work for user interactive authentication. It -takes many paramters: -.Bl -bullet -.It -An array of arrays of stages. Stages should be created with -.Fn UiaStageBuild , -and then put into an array to create a flow. Those flows should then -be put into an array and passed as this paramter. Do note that -because of the loose typing of Telodendria's Array API, it is very -easy to make mistakes here; if you are implementing a new route that -requires user interactive authentication, then refer to an existing -route so you can see how it works. -.It -An HTTP server context. This is required to set the response headers -in the event of an error. -.It -The database where user interactive authentication sessons are -persisted. -.It -The JSON request body that contains the client's -.Dv auth -object, which will be read, parsed, and handled as appropriate. -.It -A pointer to a pointer where a JSON response can be placed if -necessary. If -.Fn UiaComplete -encounters a client error, such as a failure to authenticate, or -outstanding stages that have not been completed, it will place a -JSON response here that is expected to be returned to the client. -This response will include a description of all the flows, stages, -and their parameters. -.It -A valid Telodendria configuration structure, because a few values -are read from the configuration during certain stages of the -authentication. -.El -.Pp -.Fn UiaFlowsFree -frees an array of flows, as described above. Even though the -caller constructs this array, it is convenient to free it in its -entirety in a single function call. -.Sh RETURN VALUES -.Pp -.Fn UiaStageBuild -returns an opaque structure that represents a user interactive -authentication stage, and any parameters the client needs to complete -it. It may return NULL if there is an error allocating memory. -.Pp -.Fn UiaDummyFlow -returns an array that represents a dummy authentication flow, or -NULL if it could not allocate memory for it. -.Pp -.Fn UiaComplete -returns an integer less than zero if it experiences an internal -failure, such as a failure to allocate memory, or a corrupted -database. It returns 0 if the client has remaining stages to -complete. In this case, it will have set the response headers -and the passed response pointer, so the caller should immediately -return the response to the client. This function returns 1 if the -user has successfully completed all stages. Only in this case shall -the caller proceed with its logic. -.Sh SEE ALSO -.Xr User 3 , -.Xr Db 3 , -.Xr Cron 3 diff --git a/man/man3/User.3 b/man/man3/User.3 deleted file mode 100644 index ee26ce2..0000000 --- a/man/man3/User.3 +++ /dev/null @@ -1,219 +0,0 @@ -.Dd $Mdocdate: March 6 2023 $ -.Dt USER 3 -.Os Telodendria Project -.Sh NAME -.Nm User -.Nd Convenience functions for working with local users. -.Sh SYNOPSIS -.In User.h -.Ft int -.Fn UserValidate "char *" "char *" -.Ft int -.Fn UserHistoricalValidate "char *" "char *" -.Ft int -.Fn UserExists "Db *" "char *" -.Ft User * -.Fn UserCreate "Db *" "char *" "char *" -.Ft User * -.Fn UserLock "Db *" "char *" -.Ft User * -.Fn UserAuthenticate "Db *" "char *" -.Ft int -.Fn UserUnlock "User *" -.Ft UserLoginInfo * -.Fn UserLogin "User *" "char *" "char *" "char *" "int" -.Ft char * -.Fn UserGetName "User *" -.Ft int -.Fn UserCheckPassword "User *" "char *" -.Ft int -.Fn UserSetPassword "User *" "char *" -.Ft int -.Fn UserDeactivate "User *" -.Ft HashMap * -.Fn UserGetDevices "User *" -.Ft UserAccessToken * -.Fn UserGenerateAccessToken "User *" "char *" "int" -.Ft int -.Fn UserAccessTokenSave "Db *" "UserAccessToken *" -.Ft void -.Fn UserAccessTokenFree "UserAccessToken *" -.Ft int -.Fn UserDeleteToken "User *" "char *" -.Ft int -.Fn UserDeleteTokens "User *" -.Ft UserId * -.Fn UserIdParse "char *" "char *" -.Ft void -.Fn UserIdFree "UserId *" -.Sh DESCRIPTION -The -.Nm -API provides a wrapper over the database and offers an easy way for managing -local users. It supports all of the locking mechanisms that the database does, -and provides features for authenticating local users, among other tasks. -.Pp -.Bd -literal -offset indent -typedef struct UserLoginInfo -{ - UserAccessToken *accessToken; - char *refreshToken; -} UserLoginInfo; - -typedef struct UserAccessToken -{ - char *user; - char *string; - char *deviceId; - long lifetime; -} UserAccessToken; - -typedef struct UserId -{ - char *localpart; - char *server; -} UserId; -.Ed -.Pp -.Fn UserValidate -takes a localpart and domain as separate parameters and validates it against the -rules of the Matrix specification. The reason the domain is required is because -the spec imposes limitations on the length of the user name, and the longer the -domain name is, the shorter the local part can be. This function is used to -ensure that client-provided localparts are valid on this server. -.Fn UserHistoricalValidate -is called the exact same way, except it is a little more lenient. It is used to -validate user parts on other servers, since some usernames might exist that are -not fully spec compliant, but remain in use due to historical reasons. -.Pp -.Fn UserExists -takes a localpart and checks whether or not it exists in the database. -.Pp -.Fn UserCreate -creates a new user. It takes a localpart, which is assumed to be valid, and -a password. -.Pp -.Fn UserLock -takes a localpart and obtains a database reference to the user represented by that -localpart. It behaves analogously to -.Fn DbLock , -and in fact uses it under the hood to ensure that the user can only be modified -by the thread that has locked the user. -.Fn UserUnlock -returns the user reference back to the database. It uses -.Fn DbUnlock -under the hood. -.Pp -.Fn UserAuthenticate -takes an access token, figures out what user it belongs to, and returns the -reference to that user. This function should be used by most endpoints that -require valid user authentication, since most endpoints are authenticated via -access tokens. -.Pp -.Fn UserLogin -is used for logging in a user. It takes the user's password, device ID, device -display name, and a boolean value indicating whether or not the client supports -refresh tokens. This function logs in the user and generates an access token to be -returned to the client. -.Pp -.Fn UserGetName -gets the name attached to a user object. It can be used for the few cases where -it's necessary to know the localpart of a user. -.Pp -.Fn UserCheckPassword -takes a password and verifies it against a user object. Telodendria does not -store passwords in plain text, so this function hashes the password and and -checks it against what's stored in the database. -.Pp -.Fn UserSetPassword -resets the given user's password by hashing a plain text password and -storing it in the database. -.Pp -.Fn UserDeactivate -deactivates a user such that it can no longer be used to log in, but -the username is still taken. This is to prevent future users from -pretending to be previous users of a given localpart. -.Pp -.Fn UserGetDevices -fetches the devices that belong to the user, in JSON format, -identical to what's stored in the database. In fact, this JSON is -still linked to the database, so it should not be freed with -.Fn JsonFree . -.Pp -.Fn UserAccessTokenGenerate , -.Fn UserAccessTokenSave , -and -.Fn UserAccessTokenFree -are used for managing individual access tokens on a user. They -operate on the UserAccessToken structure. -.Fn UserAccessTokenGenerate -takes the user localpart to generate the token for, the device ID, -for the token, and a boolean value indicating whether or not the token -should expire. -.Fn UserAccessTokenSave -writes the access token to the database. -.Pp -.Fn UserDeleteToken -and -.Fn UserDeleteTokens -delete a specific access token/refresh token pair, or all the access -and refresh tokens for a given user, respectively. -.Pp -.Fn UserIdParse -parses either a localpart or a fully-qualified Matrix ID. -.Fn UserIdFree -frees the result of this parsing. -.Sh RETURN VALUES -.Pp -.Fn UserValidate , -.Fn UserHistoricalValidate , -.Fn UserExists , -.Fn UserUnlock , -.Fn UserCheckPassword , -.Fn UserSetPassword , -.Fn UserDeactivate , -.Fn UserAccessTokenSave , -.Fn UserDeleteToken , -and -.Fn UserDeleteTokens -all return a boolean value. Non-zero values indicate success, and zero values -indicate failure. -.Pp -.Fn UserCreate , -.Fn UserLock , -and -.Fn UserAuthenticate -return a pointer to a User, or NULL if an error occurred. -.Pp -.Fn UserGetName -returns a pointer to the string that holds the localpart of the user represented -by the given user pointer. This pointer should not be freed by the caller , as it -is used internally and will be freed when the user is unlocked. -.Pp -.Fn UserLogin -returns a UserLoginInfo struct, or -.Dv NULL -if something goes wrong. -All this information should be returned to the client that is logging in. If the -client doesn't support refresh tokens, then refreshToken will be NULL. -.Pp -.Fn UserGetDevices -returns a JSON object that is linked to the database, or NULL if -there was an error. The result should not be freed with -.Fn JsonFree -because it is still directly attached to the database. This object -is an exact representation of what is stored on the disk. -.Pp -.Fn UserAccessTokenGenerate -generates an access token structure that should be freed when it is -no longer needed, or -.Dv NULL -if there was a memory error. -.Pp -.Fn UserIdParse -returns a UserId structure that should be freed when it is no longer -needed, or -.Dv NULL -if there was a memory error. -.Sh SEE ALSO -.Xr Db 3 diff --git a/man/man3/Util.3 b/man/man3/Util.3 deleted file mode 100644 index a9d4a37..0000000 --- a/man/man3/Util.3 +++ /dev/null @@ -1,101 +0,0 @@ -.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 .