Merge branch 'mh/tempfile'
[git/git.git] / lockfile.h
CommitLineData
697cc8ef
MH
1#ifndef LOCKFILE_H
2#define LOCKFILE_H
3
4/*
5 * File write-locks as used by Git.
6 *
2db69de8
MH
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 *
1a9d15db
MH
32 * Most of the heavy lifting is done by the tempfile module (see
33 * "tempfile.h").
2db69de8
MH
34 *
35 * Calling sequence
36 * ----------------
37 *
38 * The caller:
39 *
40 * * Allocates a `struct lock_file` either as a static variable or on
41 * the heap, initialized to zeros. Once you use the structure to
42 * call the `hold_lock_file_for_*()` family of functions, it belongs
43 * to the lockfile subsystem and its storage must remain valid
44 * throughout the life of the program (i.e. you cannot use an
45 * on-stack variable to hold this structure).
46 *
47 * * Attempts to create a lockfile by calling
48 * `hold_lock_file_for_update()` or `hold_lock_file_for_append()`.
49 *
50 * * Writes new content for the destination file by either:
51 *
52 * * writing to the file descriptor returned by the
53 * `hold_lock_file_for_*()` functions (also available via
54 * `lock->fd`).
55 *
56 * * calling `fdopen_lock_file()` to get a `FILE` pointer for the
57 * open file and writing to the file using stdio.
58 *
59 * When finished writing, the caller can:
60 *
61 * * Close the file descriptor and rename the lockfile to its final
62 * destination by calling `commit_lock_file()` or
63 * `commit_lock_file_to()`.
64 *
65 * * Close the file descriptor and remove the lockfile by calling
66 * `rollback_lock_file()`.
67 *
68 * * Close the file descriptor without removing or renaming the
69 * lockfile by calling `close_lock_file()`, and later call
70 * `commit_lock_file()`, `commit_lock_file_to()`,
71 * `rollback_lock_file()`, or `reopen_lock_file()`.
72 *
73 * Even after the lockfile is committed or rolled back, the
74 * `lock_file` object must not be freed or altered by the caller.
75 * However, it may be reused; just pass it to another call of
76 * `hold_lock_file_for_update()` or `hold_lock_file_for_append()`.
77 *
78 * If the program exits before `commit_lock_file()`,
1a9d15db
MH
79 * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
80 * tempfile module will close and remove the lockfile, thereby rolling
81 * back any uncommitted changes.
2db69de8
MH
82 *
83 * If you need to close the file descriptor you obtained from a
84 * `hold_lock_file_for_*()` function yourself, do so by calling
1a9d15db
MH
85 * `close_lock_file()`. See "tempfile.h" for more information.
86 *
87 *
88 * Under the covers, a lockfile is just a tempfile with a few helper
89 * functions. In particular, the state diagram and the cleanup
90 * machinery are all implemented in the tempfile module.
91 *
2db69de8
MH
92 *
93 * Error handling
94 * --------------
95 *
96 * The `hold_lock_file_for_*()` functions return a file descriptor on
97 * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see
98 * "flags" below). On errors, `errno` describes the reason for
99 * failure. Errors can be reported by passing `errno` to
100 * `unable_to_lock_message()` or `unable_to_lock_die()`.
101 *
102 * Similarly, `commit_lock_file`, `commit_lock_file_to`, and
103 * `close_lock_file` return 0 on success. On failure they set `errno`
104 * appropriately, do their best to roll back the lockfile, and return
105 * -1.
697cc8ef
MH
106 */
107
1a9d15db
MH
108#include "tempfile.h"
109
697cc8ef 110struct lock_file {
1a9d15db 111 struct tempfile tempfile;
697cc8ef
MH
112};
113
114/* String appended to a filename to derive the lockfile name: */
115#define LOCK_SUFFIX ".lock"
116#define LOCK_SUFFIX_LEN 5
117
2db69de8
MH
118
119/*
120 * Flags
121 * -----
122 *
123 * The following flags can be passed to `hold_lock_file_for_update()`
124 * or `hold_lock_file_for_append()`.
125 */
126
127/*
128 * If a lock is already taken for the file, `die()` with an error
129 * message. If this flag is not specified, trying to lock a file that
130 * is already locked returns -1 to the caller.
131 */
697cc8ef 132#define LOCK_DIE_ON_ERROR 1
2db69de8
MH
133
134/*
135 * Usually symbolic links in the destination path are resolved. This
136 * means that (1) the lockfile is created by adding ".lock" to the
137 * resolved path, and (2) upon commit, the resolved path is
138 * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
139 * is created by adding ".lock" to the path argument itself. This
140 * option is used, for example, when detaching a symbolic reference,
141 * which for backwards-compatibility reasons, can be a symbolic link
142 * containing the name of the referred-to-reference.
143 */
697cc8ef
MH
144#define LOCK_NO_DEREF 2
145
2db69de8
MH
146/*
147 * Attempt to create a lockfile for the file at `path` and return a
148 * file descriptor for writing to it, or -1 on error. If the file is
149 * currently locked, retry with quadratic backoff for at least
150 * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if
151 * timeout_ms is -1, retry indefinitely. The flags argument and error
152 * handling are described above.
153 */
044b6a9e
MH
154extern int hold_lock_file_for_update_timeout(
155 struct lock_file *lk, const char *path,
156 int flags, long timeout_ms);
157
2db69de8
MH
158/*
159 * Attempt to create a lockfile for the file at `path` and return a
160 * file descriptor for writing to it, or -1 on error. The flags
161 * argument and error handling are described above.
162 */
044b6a9e
MH
163static inline int hold_lock_file_for_update(
164 struct lock_file *lk, const char *path,
165 int flags)
166{
167 return hold_lock_file_for_update_timeout(lk, path, flags, 0);
168}
169
2db69de8
MH
170/*
171 * Like `hold_lock_file_for_update()`, but before returning copy the
172 * existing contents of the file (if any) to the lockfile and position
173 * its write pointer at the end of the file. The flags argument and
174 * error handling are described above.
175 */
176extern int hold_lock_file_for_append(struct lock_file *lk,
177 const char *path, int flags);
178
179/*
180 * Append an appropriate error message to `buf` following the failure
181 * of `hold_lock_file_for_update()` or `hold_lock_file_for_append()`
182 * to lock `path`. `err` should be the `errno` set by the failing
183 * call.
184 */
185extern void unable_to_lock_message(const char *path, int err,
186 struct strbuf *buf);
044b6a9e 187
2db69de8
MH
188/*
189 * Emit an appropriate error message and `die()` following the failure
190 * of `hold_lock_file_for_update()` or `hold_lock_file_for_append()`
191 * to lock `path`. `err` should be the `errno` set by the failing
192 * call.
193 */
194extern NORETURN void unable_to_lock_die(const char *path, int err);
195
196/*
197 * Associate a stdio stream with the lockfile (which must still be
198 * open). Return `NULL` (*without* rolling back the lockfile) on
199 * error. The stream is closed automatically when `close_lock_file()`
200 * is called or when the file is committed or rolled back.
201 */
1a9d15db
MH
202static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
203{
204 return fdopen_tempfile(&lk->tempfile, mode);
205}
2db69de8 206
b4fb09e4
MH
207/*
208 * Return the path of the lockfile. The return value is a pointer to a
209 * field within the lock_file object and should not be freed.
210 */
1a9d15db
MH
211static inline const char *get_lock_file_path(struct lock_file *lk)
212{
213 return get_tempfile_path(&lk->tempfile);
214}
b4fb09e4 215
1a9d15db
MH
216static inline int get_lock_file_fd(struct lock_file *lk)
217{
218 return get_tempfile_fd(&lk->tempfile);
219}
220
221static inline FILE *get_lock_file_fp(struct lock_file *lk)
222{
223 return get_tempfile_fp(&lk->tempfile);
224}
c99a4c2d 225
2db69de8
MH
226/*
227 * Return the path of the file that is locked by the specified
228 * lock_file object. The caller must free the memory.
229 */
230extern char *get_locked_file_path(struct lock_file *lk);
231
232/*
233 * If the lockfile is still open, close it (and the file pointer if it
234 * has been opened using `fdopen_lock_file()`) without renaming the
235 * lockfile over the file being locked. Return 0 upon success. On
236 * failure to `close(2)`, return a negative value and roll back the
237 * lock file. Usually `commit_lock_file()`, `commit_lock_file_to()`,
238 * or `rollback_lock_file()` should eventually be called if
239 * `close_lock_file()` succeeds.
240 */
1a9d15db
MH
241static inline int close_lock_file(struct lock_file *lk)
242{
243 return close_tempfile(&lk->tempfile);
244}
2db69de8
MH
245
246/*
247 * Re-open a lockfile that has been closed using `close_lock_file()`
248 * but not yet committed or rolled back. This can be used to implement
249 * a sequence of operations like the following:
250 *
251 * * Lock file.
252 *
253 * * Write new contents to lockfile, then `close_lock_file()` to
254 * cause the contents to be written to disk.
255 *
256 * * Pass the name of the lockfile to another program to allow it (and
257 * nobody else) to inspect the contents you wrote, while still
258 * holding the lock yourself.
259 *
260 * * `reopen_lock_file()` to reopen the lockfile. Make further updates
261 * to the contents.
262 *
263 * * `commit_lock_file()` to make the final version permanent.
264 */
1a9d15db
MH
265static inline int reopen_lock_file(struct lock_file *lk)
266{
267 return reopen_tempfile(&lk->tempfile);
268}
2db69de8
MH
269
270/*
271 * Commit the change represented by `lk`: close the file descriptor
272 * and/or file pointer if they are still open and rename the lockfile
273 * to its final destination. Return 0 upon success. On failure, roll
274 * back the lock file and return -1, with `errno` set to the value
275 * from the failing call to `close(2)` or `rename(2)`. It is a bug to
276 * call `commit_lock_file()` for a `lock_file` object that is not
277 * currently locked.
278 */
279extern int commit_lock_file(struct lock_file *lk);
280
281/*
282 * Like `commit_lock_file()`, but rename the lockfile to the provided
283 * `path`. `path` must be on the same filesystem as the lock file.
284 */
1a9d15db
MH
285static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
286{
287 return rename_tempfile(&lk->tempfile, path);
288}
2db69de8
MH
289
290/*
291 * Roll back `lk`: close the file descriptor and/or file pointer and
292 * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
293 * for a `lock_file` object that has already been committed or rolled
294 * back.
295 */
1a9d15db
MH
296static inline void rollback_lock_file(struct lock_file *lk)
297{
298 delete_tempfile(&lk->tempfile);
299}
697cc8ef
MH
300
301#endif /* LOCKFILE_H */