Signed-off-by: Carlos Eduardo <carana2...@gmail.com> --- doc/libunixonacid/unix-transactional.html | 99 ++++++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-)
diff --git a/doc/libunixonacid/unix-transactional.html b/doc/libunixonacid/unix-transactional.html index 7a6e5b5..bab45a0 100644 --- 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> -- 2.44.0
