From f2c2888c870bc2c819e63ab3f284f7a96e022554 Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Mon, 6 Mar 2023 22:29:46 +0000
Subject: [PATCH] Document DbList() and DbListFree()

---
 TODO.txt      |  2 +-
 man/man3/Db.3 | 18 +++++++++++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/TODO.txt b/TODO.txt
index 94bf18c..a0d915d 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -25,7 +25,7 @@ Milestone: v0.2.0
 [~] Documentation
     [x] User functions
     [x] Json functions
-    [ ] Db functions
+    [x] Db functions
     [ ] Uia (move docs from Matrix)
 
 [x] Convert proposals to man pages
diff --git a/man/man3/Db.3 b/man/man3/Db.3
index b2233cf..06dd8e7 100644
--- a/man/man3/Db.3
+++ b/man/man3/Db.3
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: January 9 2023 $
+.Dd $Mdocdate: March 6 2023 $
 .Dt DB 3
 .Os Telodendria Project
 .Sh NAME
@@ -20,6 +20,10 @@
 .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
@@ -77,6 +81,14 @@ of that nature.
 .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
@@ -99,6 +111,10 @@ 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