doc: misc update

- Add manual section for the utility library.
- Add comments for utility library functions.
- Fix installation path for backends and fsck handlers.

doc/bookmarkfs.texi

@@ -171,6 +171,58 @@ On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and
 On FreeBSD, @freebsdmanpage{capsicum, 4} is used.
 
 
+@node The Utility Library
+@section The Utility Library
+
+The BookmarkFS Utility Library implements various common utility functions.
+It is used internally by most of BookmarkFS's components, including
+the backends (@pxref{Backends}) and the @command{mount.bookmarkfs} program.
+
+Typically, the library is built into a shared object, and installed as:
+
+@example
+@var{$@{libdir@}}/bookmarkfs_util@var{$@{shlib_suffix@}}
+@end example
+
+@table @var
+@item $@{libdir@}
+Presumably @file{@var{$@{prefix@}}/lib}.
+@xref{Uniform,, The Uniform Naming Scheme, automake, GNU Automake}.
+
+@item $@{shlib_suffix@}
+The common filename extension for shared library files on the current platform
+(e.g., @file{.so} on GNU/Linux and FreeBSD).
+@end table
+
+Public headers are installed under @file{@var{$@{pkgincludedir@}}}
+(presumably @file{@var{$@{prefix@}}/include/bookmarkfs}).
+To use the library functions, include the following headers as needed:
+
+@table @file
+@item hash.h
+Non-cryptographic hash function.
+
+@item hashmap.h
+A simple hashtable implementation.
+
+@item prng.h
+Non-cryptographic pseudo-random number generator.
+
+@item sandbox.h
+A simple sandbox implementation. @xref{Sandboxing}.
+
+@item version.h
+Get version and feature information of the library.
+
+@item watcher.h
+Single-file filesystem watcher.
+@end table
+
+Usage of the library functions is rather simple and straightforward,
+thus there's currently no dedicated manual sections.
+Refer to the comments in the corresponding header files for details.
+
+
 @node Programs
 @chapter Programs
 
@@ -1101,7 +1153,7 @@ application bookmarks.
 Typically, backends are built into shared libraries, and are installed as:
 
 @example
-@var{$@{pkglibdir@}}/backend-@var{$@{name@}}@var{$@{shlib_suffix@}}
+@var{$@{pkglibdir@}}/backend_@var{$@{name@}}@var{$@{shlib_suffix@}}
 @end example
 
 @table @var
@@ -1450,6 +1502,7 @@ A bit array of the following flags:
 @table @code
 @item BOOKMARKFS_BACKEND_LIB_READY
 Indicates that the utility library is already initialized.
+@xref{The Utility Library}.
 
 Some frontend programs use the utility library.
 If they do, they always initialize it before initializing the backend.
@@ -1862,7 +1915,7 @@ Like backends, filesystem-check handlers are typically built into
 shared libraries, and are installed as:
 
 @example
-@var{$@{pkglibdir@}}/fsck-handler-@var{$@{name@}}@var{$@{shlib_suffix@}}
+@var{$@{pkglibdir@}}/fsck_handler_@var{$@{name@}}@var{$@{shlib_suffix@}}
 @end example
 
 @table @var

src/sandbox.h

@@ -25,10 +25,30 @@
 
 #include <stdint.h>
 
+/**
+ * Only perform read operations on dirfd (and the files beneath).
+ */
 #define SANDBOX_READONLY     ( 1u << 0 )
+/**
+ * Do not use landlock for sandoxing.
+ * Ignored on non-Linux platforms.
+ */
 #define SANDBOX_NO_LANDLOCK  ( 1u << 1 )
+/**
+ * sandbox_enter() does nothing and returns successfully.
+ */
 #define SANDBOX_NOOP         ( 1u << 2 )
 
+/**
+ * Instruct the current process (or thread, depending on
+ * the implementation) to enter sandbox.
+ * In sandbox, the process has limited access to system calls.
+ *
+ * If dirfd is non-negative, it should refer to a directory
+ * which the process needs to access.
+ *
+ * Returns 0 on success, -1 on failure.
+ */
 int
 sandbox_enter (
     int      dirfd,

src/version.h

@@ -46,6 +46,12 @@
 #define BOOKMARKFS_FEAT_SANDBOX           ( 1u << 26 )
 #define BOOKMARKFS_FEAT_SANDBOX_LANDLOCK  ( 1u << 27 )
 
+/**
+ * Obtain version and feature information of the utility library.
+ *
+ * Returns a combination of the version number
+ * and BOOKMARKFS_FEAT_xxx flags.
+ */
 uint32_t
 bookmarkfs_lib_version (void);