unix-transactional.html (5109B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the unix-transactional library interface</title> 7 <meta name="Description" content="skalibs: the unix-transactional library interface" /> 8 <meta name="Keywords" content="skalibs c unix-transactional library libunixonacid" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libunixonacid</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">www.skarnet.org</a> 19 </p> 20 21 <h1> The <tt>unix-transactional</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/unix-transactional.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>unix-transactional</tt> provides an API for transactional/reliable 32 filesystem operations. 33 </p> 34 35 <p> 36 Most functions are <a href="../libstddjb/safewrappers.html">safe wrappers</a> 37 around the Unix <tt>*at</tt> system calls. They differ from the traditional 38 system calls (safe-wrapped in 39 <a href="../libstddjb/djbunix.html"><tt>djbunix</tt></a> and 40 <a href="../libstddjb/allreadwrite.html"><tt>allreadwrite</tt></a>) in that 41 they take an additional argument <em>fd</em>. When <em>file</em> is relative, 42 it is opened relative to the directory associated with the file descriptor 43 <em>fd</em> instead of the current working directory. 44 </p> 45 46 <p> 47 If <em>file</em> is absolute, they are equivalent to their <tt>djbunix</tt> 48 and <tt>allreadwrite</tt> counterparts. 49 </p> 50 51 <p> 52 On systems that do not implement the <tt>*at</tt> system calls, these 53 functions fall back to changing the current working directory, opening 54 <em>file</em> with the corresponding <tt>libstddjb</tt> function, and restoring 55 the original working directory using <tt>fd_chdir</tt>. 56 </p> 57 58 <h2> Functions </h2> 59 60 <h3> Basic fd operations relative to a directory </h3> 61 62 <p> 63 <code> int open2_at (int fd, char const *file, int flags) </code><br /> 64 Safe wrapper around 65 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html">openat()</a> 66 when it takes 2 arguments. 67 </p> 68 69 <p> 70 <code> int open3_at (int fd, char const *file, int flags) </code><br /> 71 Safe wrapper around 72 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html">openat()</a> 73 when it takes 3 arguments. 74 </p> 75 76 <p> 77 <code> int access_at (int fd, char const *file, int amode, unsigned int flag) </code><br /> 78 Calls 79 <a href="https://pubs.opengroup.org/onlinepubs/9699919799.orig/functions/faccessat.html">faccessat()</a> 80 with <em>flags</em> set either to zero, or <tt>AT_EACCESS</tt>, if <em>flag</em> is nonzero. 81 This function ensures a fall back on platforms without <tt>*at</tt> system calls. 82 </p> 83 84 <p> 85 <code> int stat_at (int fd, char const *file, struct stat *st) </code><br /> 86 <code> int lstat_at (int fd, char const *file, struct stat *st) </code><br /> 87 Calls 88 <a href="https://pubs.opengroup.org/onlinepubs/007904875/functions/stat.html">fstatat()</a> 89 without and with the <tt>AT_SYMLINK_NOFOLLOW</tt> flag, respectively. 90 This function ensures a fall back on platforms without <tt>*at</tt> system calls. 91 </p> 92 93 <p> 94 <code> DIR *opendir_at (int dfd, char const *name) </code><br /> 95 Relative version of 96 <a href="https://pubs.opengroup.org/onlinepubs/009604599/functions/opendir.html">opendir()</a>. 97 </p> 98 99 <p> 100 <code> int opengetlnclose (char const *file, stralloc *sa, int sep) </code><br /> 101 <code> int opengetlnclose_at (int dirfd, char const *file, stralloc *sa, int sep) </code><br /> 102 Slurps <em>file</em> (relative to <em>dirfd</em> in the <tt>_at</tt> version) 103 into *<em>sa</em> up to (and including) the first <em>sep</em> character. 104 Returns 1 on success, 0 if some bytes were read but no <em>sep</em> was found, 105 -1 EPIPE on immediate EOF and -1 (and sets errno) on error. 106 </p> 107 108 <p> 109 <code> size_t openwritenclose_at (int dirfd, char const *file, char const *s, size_t n) </code><br /> 110 <code> size_t openwritevnclose_at (int dirfd, char const *file, struct iovec const *v, unsigned int n) </code><br /> 111 Relative versions of <tt>openwritenclose_unsafe_sync</tt> and 112 <tt>openwritevnclose_unsafe_sync</tt> in <tt>djbunix</tt>, except for the fact 113 that they return the number of bytes written instead of just 1 and 0. 114 </p> 115 116 <p> 117 The remaining functions are named after their corresponding <tt>libstddjb</tt> 118 functions. 119 </p> 120 121 <h3> Atomic filesystem deletion </h3> 122 123 <p> 124 <code> int atomic_rm_rf (char const *filename) </code><br /> 125 <code> int atomic_rm_rf_tmp (char const *filename, stralloc *tmp) </code></br> 126 Renames <em>filename</em> to a unique name and deletes its filesystem subtree. 127 The difference between these two functions is the same as that between 128 <tt>rm_rf</tt> and <tt>rm_rf_tmp</tt> in <tt>djbunix</tt>. 129 </p> 130 131 </body> 132 </html>