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