commit c96dc580363e6fc15911522c16903a954f144db2
parent 3b4c330e5b5afb6dd3959b468830d19c8cde58bb
Author: Carlos Eduardo <carana2099@gmail.com>
Date: Sat, 27 Apr 2024 14:12:08 -0300
document unix-transactional
Signed-off-by: Carlos Eduardo <carana2099@gmail.com>
Diffstat:
1 file changed, 98 insertions(+), 1 deletion(-)
diff --git a/doc/libunixonacid/unix-transactional.html b/doc/libunixonacid/unix-transactional.html
@@ -28,7 +28,104 @@ and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
<h2> General information </h2>
<p>
-FIXME: to be completed.
+ <tt>unix-transactional</tt> provides an API for transactional/reliable
+filesystem operations.
+</p>
+
+<p>
+ Most functions are <a href="../libstddjb/safewrappers.html">safe wrappers</a>
+around the Unix <tt>*at</tt> system calls. They differ from the traditional
+system calls (safe-wrapped in
+<a href="../libstddjb/djbunix.html"><tt>djbunix</tt></a> and
+<a href="../libstddjb/allreadwrite.html"><tt>allreadwrite</tt></a>) in that
+they take an additional argument <em>fd</em>. When <em>file</em> is relative,
+it is opened relative to the directory associated with the file descriptor
+<em>fd</em> instead of the current working directory.
+</p>
+
+<p>
+ If <em>file</em> is absolute, they are equivalent to their <tt>djbunix</tt>
+ and <tt>allreadwrite</tt> counterparts.
+</p>
+
+<p>
+ On systems that do not implement the <tt>*at</tt> system calls, these
+functions fall back to changing the current working directory, opening
+<em>file</em> with the corresponding <tt>libstddjb</tt> function, and restoring
+the original working directory using <tt>fd_chdir</tt>.
+</p>
+
+<h2> Functions </h2>
+
+<h3> Basic fd operations relative to a directory </h3>
+
+<p>
+<code> int open2_at (int fd, char const *file, int flags) </code><br />
+Safe wrapper around
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html">openat()</a>
+when it takes 2 arguments.
+</p>
+
+<p>
+<code> int open3_at (int fd, char const *file, int flags) </code><br />
+Safe wrapper around
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html">openat()</a>
+when it takes 3 arguments.
+</p>
+
+<p>
+<code> int access_at (int fd, char const *file, int amode, unsigned int flag) </code><br />
+Calls
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799.orig/functions/faccessat.html">faccessat()</a>
+with <em>flags</em> set either to zero, or <tt>AT_EACCESS</tt>, if <em>flag</em> is nonzero.
+This function ensures a fall back on platforms without <tt>*at</tt> system calls.
+</p>
+
+<p>
+<code> int stat_at (int fd, char const *file, struct stat *st) </code><br />
+<code> int lstat_at (int fd, char const *file, struct stat *st) </code><br />
+Calls
+<a href="https://pubs.opengroup.org/onlinepubs/007904875/functions/stat.html">fstatat()</a>
+without and with the <tt>AT_SYMLINK_NOFOLLOW</tt> flag, respectively.
+This function ensures a fall back on platforms without <tt>*at</tt> system calls.
+</p>
+
+<p>
+<code> DIR *opendir_at (int dfd, char const *name) </code><br />
+Relative version of
+<a href="https://pubs.opengroup.org/onlinepubs/009604599/functions/opendir.html">opendir()</a>.
+</p>
+
+<p>
+<code> int opengetlnclose (char const *file, stralloc *sa, int sep) </code><br />
+<code> int opengetlnclose_at (int dirfd, char const *file, stralloc *sa, int sep) </code><br />
+Slurps <em>file</em> (relative to <em>dirfd</em> in the <tt>_at</tt> version)
+into *<em>sa</em> up to (and including) the first <em>sep</em> character.
+Returns 1 on success, 0 if some bytes were read but no <em>sep</em> was found,
+-1 EPIPE on immediate EOF and -1 (and sets errno) on error.
+</p>
+
+<p>
+<code> size_t openwritenclose_at (int dirfd, char const *file, char const *s, size_t n) </code><br />
+<code> size_t openwritevnclose_at (int dirfd, char const *file, struct iovec const *v, unsigned int n) </code><br />
+Relative versions of <tt>openwritenclose_unsafe_sync</tt> and
+<tt>openwritevnclose_unsafe_sync</tt> in <tt>djbunix</tt>, except for the fact
+that they return the number of bytes written instead of just 1 and 0.
+</p>
+
+<p>
+ The remaining functions are named after their corresponding <tt>libstddjb</tt>
+ functions.
+</p>
+
+<h3> Atomic filesystem deletion </h3>
+
+<p>
+<code> int atomic_rm_rf (char const *filename) </code><br />
+<code> int atomic_rm_rf_tmp (char const *filename, stralloc *tmp) </code></br>
+Renames <em>filename</em> to a unique name and deletes its filesystem subtree.
+The difference between these two functions is the same as that between
+<tt>rm_rf</tt> and <tt>rm_rf_tmp</tt> in <tt>djbunix</tt>.
</p>
</body>
