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