1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>skalibs: the unix-transactional library interface</title>
<meta name="Description" content="skalibs: the unix-transactional library interface" />
<meta name="Keywords" content="skalibs c unix-transactional library libunixonacid" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libunixonacid</a><br />
<a href="../libskarnet.html">libskarnet</a><br />
<a href="../index.html">skalibs</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">www.skarnet.org</a>
</p>
<h1> The <tt>unix-transactional</tt> library interface </h1>
<p>
The following functions are declared in the <tt>skalibs/unix-transactional.h</tt> header,
and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
</p>
<h2> General information </h2>
<p>
<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>
</html>
|
