]>
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 | * | |
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 | 110 | struct 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 |
154 | extern 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 |
163 | static 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 | */ | |
176 | extern 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 | */ | |
185 | extern 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 | */ | |
194 | extern 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 |
202 | static 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 |
211 | static inline const char *get_lock_file_path(struct lock_file *lk) |
212 | { | |
213 | return get_tempfile_path(&lk->tempfile); | |
214 | } | |
b4fb09e4 | 215 | |
1a9d15db MH |
216 | static inline int get_lock_file_fd(struct lock_file *lk) |
217 | { | |
218 | return get_tempfile_fd(&lk->tempfile); | |
219 | } | |
220 | ||
221 | static 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 | */ | |
230 | extern 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 |
241 | static 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 |
265 | static 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 | */ | |
279 | extern 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 |
285 | static 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 |
296 | static inline void rollback_lock_file(struct lock_file *lk) |
297 | { | |
298 | delete_tempfile(&lk->tempfile); | |
299 | } | |
697cc8ef MH |
300 | |
301 | #endif /* LOCKFILE_H */ |