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