freshlybakedca.ke
Git fork
1#ifndef LOCKFILE_H
2#define LOCKFILE_H
3
4/*
5 * File write-locks as used by Git.
6 *
7 * The lockfile API serves two purposes:
8 *
9 * * Mutual exclusion and atomic file updates. When we want to change
10 * a file, we create a lockfile `<filename>.lock`, write the new
11 * file contents into it, and then rename the lockfile to its final
12 * destination `<filename>`. We create the `<filename>.lock` file
13 * with `O_CREAT|O_EXCL` so that we can notice and fail if somebody
14 * else has already locked the file, then atomically rename the
15 * lockfile to its final destination to commit the changes and
16 * unlock the file.
17 *
18 * * Automatic cruft removal. If the program exits after we lock a
19 * file but before the changes have been committed, we want to make
20 * sure that we remove the lockfile. This is done by remembering the
21 * lockfiles we have created in a linked list and setting up an
22 * `atexit(3)` handler and a signal handler that clean up the
23 * lockfiles. This mechanism ensures that outstanding lockfiles are
24 * cleaned up if the program exits (including when `die()` is
25 * called) or if the program is terminated by a signal.
26 *
27 * Please note that lockfiles only block other writers. Readers do not
28 * block, but they are guaranteed to see either the old contents of
29 * the file or the new contents of the file (assuming that the
30 * filesystem implements `rename(2)` atomically).
31 *
32 * Most of the heavy lifting is done by the tempfile module (see
33 * "tempfile.h").
34 *
35 * Calling sequence
36 * ----------------
37 *
38 * The caller:
39 *
40 * * Allocates a `struct lock_file` with whatever storage duration you
41 * desire. The struct does not have to be initialized before being
42 * used, but it is good practice to do so using by setting it to
43 * all-zeros (or using the LOCK_INIT macro). This puts the object in a
44 * consistent state that allows you to call rollback_lock_file() even
45 * if the lock was never taken (in which case it is a noop).
46 *
47 * * Attempts to create a lockfile by calling `hold_lock_file_for_update()`.
48 *
49 * * Writes new content for the destination file by either:
50 *
51 * * writing to the file descriptor returned by the
52 * `hold_lock_file_for_*()` functions (also available via
53 * `lock->fd`).
54 *
55 * * calling `fdopen_lock_file()` to get a `FILE` pointer for the
56 * open file and writing to the file using stdio.
57 *
58 * Note that the file descriptor returned by hold_lock_file_for_update()
59 * is marked O_CLOEXEC, so the new contents must be written by the
60 * current process, not a spawned one.
61 *
62 * When finished writing, the caller can:
63 *
64 * * Close the file descriptor and rename the lockfile to its final
65 * destination by calling `commit_lock_file()` or
66 * `commit_lock_file_to()`.
67 *
68 * * Close the file descriptor and remove the lockfile by calling
69 * `rollback_lock_file()`.
70 *
71 * * Close the file descriptor without removing or renaming the
72 * lockfile by calling `close_lock_file_gently()`, and later call
73 * `commit_lock_file()`, `commit_lock_file_to()`,
74 * `rollback_lock_file()`, or `reopen_lock_file()`.
75 *
76 * After the lockfile is committed or rolled back, the `lock_file`
77 * object can be discarded or reused.
78 *
79 * If the program exits before `commit_lock_file()`,
80 * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
81 * tempfile module will close and remove the lockfile, thereby rolling
82 * back any uncommitted changes.
83 *
84 * If you need to close the file descriptor you obtained from a
85 * `hold_lock_file_for_*()` function yourself, do so by calling
86 * `close_lock_file_gently()`. See "tempfile.h" for more information.
87 *
88 *
89 * Under the covers, a lockfile is just a tempfile with a few helper
90 * functions. In particular, the state diagram and the cleanup
91 * machinery are all implemented in the tempfile module.
92 *
93 * Permission bits
94 * ---------------
95 *
96 * If you call either `hold_lock_file_for_update_mode` or
97 * `hold_lock_file_for_update_timeout_mode`, you can specify a suggested
98 * mode for the underlying temporary file. Note that the file isn't
99 * guaranteed to have this exact mode, since it may be limited by either
100 * the umask, 'core.sharedRepository', or both. See `adjust_shared_perm`
101 * for more.
102 *
103 * Error handling
104 * --------------
105 *
106 * The `hold_lock_file_for_*()` functions return a file descriptor on
107 * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see
108 * "flags" below). On errors, `errno` describes the reason for
109 * failure. Errors can be reported by passing `errno` to
110 * `unable_to_lock_message()` or `unable_to_lock_die()`.
111 *
112 * Similarly, `commit_lock_file`, `commit_lock_file_to`, and
113 * `close_lock_file` return 0 on success. On failure they set `errno`
114 * appropriately and return -1. The `commit` variants (but not `close`)
115 * do their best to delete the temporary file before returning.
116 */
117
118#include "tempfile.h"
119
120struct lock_file {
121 struct tempfile *tempfile;
122};
123
124#define LOCK_INIT { 0 }
125
126/* String appended to a filename to derive the lockfile name: */
127#define LOCK_SUFFIX ".lock"
128#define LOCK_SUFFIX_LEN 5
129
130
131/*
132 * Flags
133 * -----
134 *
135 * The following flags can be passed to `hold_lock_file_for_update()`.
136 */
137
138/*
139 * If a lock is already taken for the file, `die()` with an error
140 * message. If this flag is not specified, trying to lock a file that
141 * is already locked silently returns -1 to the caller, or ...
142 */
143#define LOCK_DIE_ON_ERROR 1
144
145/*
146 * ... this flag can be passed instead to return -1 and give the usual
147 * error message upon an error.
148 */
149#define LOCK_REPORT_ON_ERROR 4
150
151/*
152 * Usually symbolic links in the destination path are resolved. This
153 * means that (1) the lockfile is created by adding ".lock" to the
154 * resolved path, and (2) upon commit, the resolved path is
155 * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
156 * is created by adding ".lock" to the path argument itself. This
157 * option is used, for example, when detaching a symbolic reference,
158 * which for backwards-compatibility reasons, can be a symbolic link
159 * containing the name of the referred-to-reference.
160 */
161#define LOCK_NO_DEREF 2
162
163/*
164 * Attempt to create a lockfile for the file at `path` and return a
165 * file descriptor for writing to it, or -1 on error. If the file is
166 * currently locked, retry with quadratic backoff for at least
167 * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if
168 * timeout_ms is -1, retry indefinitely. The flags argument, error
169 * handling, and mode are described above.
170 */
171int hold_lock_file_for_update_timeout_mode(
172 struct lock_file *lk, const char *path,
173 int flags, long timeout_ms, int mode);
174
175static inline int hold_lock_file_for_update_timeout(
176 struct lock_file *lk, const char *path,
177 int flags, long timeout_ms)
178{
179 return hold_lock_file_for_update_timeout_mode(lk, path, flags,
180 timeout_ms, 0666);
181}
182
183/*
184 * Attempt to create a lockfile for the file at `path` and return a
185 * file descriptor for writing to it, or -1 on error. The flags
186 * argument and error handling are described above.
187 */
188static inline int hold_lock_file_for_update(
189 struct lock_file *lk, const char *path,
190 int flags)
191{
192 return hold_lock_file_for_update_timeout(lk, path, flags, 0);
193}
194
195static inline int hold_lock_file_for_update_mode(
196 struct lock_file *lk, const char *path,
197 int flags, int mode)
198{
199 return hold_lock_file_for_update_timeout_mode(lk, path, flags, 0, mode);
200}
201
202/*
203 * Return a nonzero value iff `lk` is currently locked.
204 */
205static inline int is_lock_file_locked(struct lock_file *lk)
206{
207 return is_tempfile_active(lk->tempfile);
208}
209
210/*
211 * Append an appropriate error message to `buf` following the failure
212 * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
213 * `errno` set by the failing call.
214 */
215void unable_to_lock_message(const char *path, int err,
216 struct strbuf *buf);
217
218/*
219 * Emit an appropriate error message and `die()` following the failure
220 * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
221 * `errno` set by the failing
222 * call.
223 */
224NORETURN void unable_to_lock_die(const char *path, int err);
225
226/*
227 * Associate a stdio stream with the lockfile (which must still be
228 * open). Return `NULL` (*without* rolling back the lockfile) on
229 * error. The stream is closed automatically when
230 * `close_lock_file_gently()` is called or when the file is committed or
231 * rolled back.
232 */
233static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
234{
235 return fdopen_tempfile(lk->tempfile, mode);
236}
237
238/*
239 * Return the path of the lockfile. The return value is a pointer to a
240 * field within the lock_file object and should not be freed.
241 */
242static inline const char *get_lock_file_path(struct lock_file *lk)
243{
244 return get_tempfile_path(lk->tempfile);
245}
246
247static inline int get_lock_file_fd(struct lock_file *lk)
248{
249 return get_tempfile_fd(lk->tempfile);
250}
251
252static inline FILE *get_lock_file_fp(struct lock_file *lk)
253{
254 return get_tempfile_fp(lk->tempfile);
255}
256
257/*
258 * Return the path of the file that is locked by the specified
259 * lock_file object. The caller must free the memory.
260 */
261char *get_locked_file_path(struct lock_file *lk);
262
263/*
264 * If the lockfile is still open, close it (and the file pointer if it
265 * has been opened using `fdopen_lock_file()`) without renaming the
266 * lockfile over the file being locked. Return 0 upon success. On
267 * failure to `close(2)`, return a negative value (the lockfile is not
268 * rolled back). Usually `commit_lock_file()`, `commit_lock_file_to()`,
269 * or `rollback_lock_file()` should eventually be called.
270 */
271static inline int close_lock_file_gently(struct lock_file *lk)
272{
273 return close_tempfile_gently(lk->tempfile);
274}
275
276/*
277 * Re-open a lockfile that has been closed using `close_lock_file_gently()`
278 * but not yet committed or rolled back. This can be used to implement
279 * a sequence of operations like the following:
280 *
281 * * Lock file.
282 *
283 * * Write new contents to lockfile, then `close_lock_file_gently()` to
284 * cause the contents to be written to disk.
285 *
286 * * Pass the name of the lockfile to another program to allow it (and
287 * nobody else) to inspect the contents you wrote, while still
288 * holding the lock yourself.
289 *
290 * * `reopen_lock_file()` to reopen the lockfile, truncating the existing
291 * contents. Write out the new contents.
292 *
293 * * `commit_lock_file()` to make the final version permanent.
294 */
295static inline int reopen_lock_file(struct lock_file *lk)
296{
297 return reopen_tempfile(lk->tempfile);
298}
299
300/*
301 * Commit the change represented by `lk`: close the file descriptor
302 * and/or file pointer if they are still open and rename the lockfile
303 * to its final destination. Return 0 upon success. On failure, roll
304 * back the lock file and return -1, with `errno` set to the value
305 * from the failing call to `close(2)` or `rename(2)`. It is a bug to
306 * call `commit_lock_file()` for a `lock_file` object that is not
307 * currently locked.
308 */
309int commit_lock_file(struct lock_file *lk);
310
311/*
312 * Like `commit_lock_file()`, but rename the lockfile to the provided
313 * `path`. `path` must be on the same filesystem as the lock file.
314 */
315static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
316{
317 return rename_tempfile(&lk->tempfile, path);
318}
319
320/*
321 * Roll back `lk`: close the file descriptor and/or file pointer and
322 * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
323 * for a `lock_file` object that has already been committed or rolled
324 * back. No error will be returned in this case.
325 */
326static inline int rollback_lock_file(struct lock_file *lk)
327{
328 return delete_tempfile(&lk->tempfile);
329}
330
331#endif /* LOCKFILE_H */