| 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` with whatever storage duration you |
| 41 | * desire. The struct does not have to be initialized before being |
| 42 | * used, but it is good practice to do so using by setting it to |
| 43 | * all-zeros (or using the LOCK_INIT macro). This puts the object in a |
| 44 | * consistent state that allows you to call rollback_lock_file() even |
| 45 | * if the lock was never taken (in which case it is a noop). |
| 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_gently()`, and later call |
| 73 | * `commit_lock_file()`, `commit_lock_file_to()`, |
| 74 | * `rollback_lock_file()`, or `reopen_lock_file()`. |
| 75 | * |
| 76 | * After the lockfile is committed or rolled back, the `lock_file` |
| 77 | * object can be discarded or reused. |
| 78 | * |
| 79 | * If the program exits before `commit_lock_file()`, |
| 80 | * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the |
| 81 | * tempfile module will close and remove the lockfile, thereby rolling |
| 82 | * back any uncommitted changes. |
| 83 | * |
| 84 | * If you need to close the file descriptor you obtained from a |
| 85 | * `hold_lock_file_for_*()` function yourself, do so by calling |
| 86 | * `close_lock_file_gently()`. See "tempfile.h" for more information. |
| 87 | * |
| 88 | * |
| 89 | * Under the covers, a lockfile is just a tempfile with a few helper |
| 90 | * functions. In particular, the state diagram and the cleanup |
| 91 | * machinery are all implemented in the tempfile module. |
| 92 | * |
| 93 | * Permission bits |
| 94 | * --------------- |
| 95 | * |
| 96 | * If you call either `hold_lock_file_for_update_mode` or |
| 97 | * `hold_lock_file_for_update_timeout_mode`, you can specify a suggested |
| 98 | * mode for the underlying temporary file. Note that the file isn't |
| 99 | * guaranteed to have this exact mode, since it may be limited by either |
| 100 | * the umask, 'core.sharedRepository', or both. See `adjust_shared_perm` |
| 101 | * for more. |
| 102 | * |
| 103 | * Error handling |
| 104 | * -------------- |
| 105 | * |
| 106 | * The `hold_lock_file_for_*()` functions return a file descriptor on |
| 107 | * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see |
| 108 | * "flags" below). On errors, `errno` describes the reason for |
| 109 | * failure. Errors can be reported by passing `errno` to |
| 110 | * `unable_to_lock_message()` or `unable_to_lock_die()`. |
| 111 | * |
| 112 | * Similarly, `commit_lock_file`, `commit_lock_file_to`, and |
| 113 | * `close_lock_file` return 0 on success. On failure they set `errno` |
| 114 | * appropriately and return -1. The `commit` variants (but not `close`) |
| 115 | * do their best to delete the temporary file before returning. |
| 116 | */ |
| 117 | |
| 118 | #include "tempfile.h" |
| 119 | |
| 120 | struct lock_file { |
| 121 | struct tempfile *tempfile; |
| 122 | struct tempfile *pid_tempfile; |
| 123 | }; |
| 124 | |
| 125 | #define LOCK_INIT { 0 } |
| 126 | |
| 127 | /* String appended to a filename to derive the lockfile name: */ |
| 128 | #define LOCK_SUFFIX ".lock" |
| 129 | #define LOCK_SUFFIX_LEN 5 |
| 130 | |
| 131 | /* |
| 132 | * PID file naming: for a lock file "foo.lock", the PID file is "foo~pid.lock". |
| 133 | * The tilde is forbidden in refnames and allowed in Windows filenames, avoiding |
| 134 | * namespace collisions (e.g., refs "foo" and "foo~pid" cannot both exist). |
| 135 | */ |
| 136 | #define LOCK_PID_INFIX "~pid" |
| 137 | #define LOCK_PID_INFIX_LEN 4 |
| 138 | |
| 139 | /* Maximum length for PID file content */ |
| 140 | #define LOCK_PID_MAXLEN 32 |
| 141 | |
| 142 | /* |
| 143 | * Whether to create PID files alongside lock files. |
| 144 | * Configured via core.lockfilePid (boolean). |
| 145 | */ |
| 146 | extern int lockfile_pid_enabled; |
| 147 | |
| 148 | /* |
| 149 | * Flags |
| 150 | * ----- |
| 151 | * |
| 152 | * The following flags can be passed to `hold_lock_file_for_update()`. |
| 153 | */ |
| 154 | |
| 155 | /* |
| 156 | * If a lock is already taken for the file, `die()` with an error |
| 157 | * message. If this flag is not specified, trying to lock a file that |
| 158 | * is already locked silently returns -1 to the caller, or ... |
| 159 | */ |
| 160 | #define LOCK_DIE_ON_ERROR 1 |
| 161 | |
| 162 | /* |
| 163 | * ... this flag can be passed instead to return -1 and give the usual |
| 164 | * error message upon an error. |
| 165 | */ |
| 166 | #define LOCK_REPORT_ON_ERROR 4 |
| 167 | |
| 168 | /* |
| 169 | * Usually symbolic links in the destination path are resolved. This |
| 170 | * means that (1) the lockfile is created by adding ".lock" to the |
| 171 | * resolved path, and (2) upon commit, the resolved path is |
| 172 | * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile |
| 173 | * is created by adding ".lock" to the path argument itself. This |
| 174 | * option is used, for example, when detaching a symbolic reference, |
| 175 | * which for backwards-compatibility reasons, can be a symbolic link |
| 176 | * containing the name of the referred-to-reference. |
| 177 | */ |
| 178 | #define LOCK_NO_DEREF 2 |
| 179 | |
| 180 | /* |
| 181 | * Attempt to create a lockfile for the file at `path` and return a |
| 182 | * file descriptor for writing to it, or -1 on error. If the file is |
| 183 | * currently locked, retry with quadratic backoff for at least |
| 184 | * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if |
| 185 | * timeout_ms is -1, retry indefinitely. The flags argument, error |
| 186 | * handling, and mode are described above. |
| 187 | */ |
| 188 | int hold_lock_file_for_update_timeout_mode( |
| 189 | struct lock_file *lk, const char *path, |
| 190 | int flags, long timeout_ms, int mode); |
| 191 | |
| 192 | static inline int hold_lock_file_for_update_timeout( |
| 193 | struct lock_file *lk, const char *path, |
| 194 | int flags, long timeout_ms) |
| 195 | { |
| 196 | return hold_lock_file_for_update_timeout_mode(lk, path, flags, |
| 197 | timeout_ms, 0666); |
| 198 | } |
| 199 | |
| 200 | /* |
| 201 | * Attempt to create a lockfile for the file at `path` and return a |
| 202 | * file descriptor for writing to it, or -1 on error. The flags |
| 203 | * argument and error handling are described above. |
| 204 | */ |
| 205 | static inline int hold_lock_file_for_update( |
| 206 | struct lock_file *lk, const char *path, int flags) |
| 207 | { |
| 208 | return hold_lock_file_for_update_timeout(lk, path, flags, 0); |
| 209 | } |
| 210 | |
| 211 | static inline int hold_lock_file_for_update_mode( |
| 212 | struct lock_file *lk, const char *path, |
| 213 | int flags, int mode) |
| 214 | { |
| 215 | return hold_lock_file_for_update_timeout_mode(lk, path, flags, 0, mode); |
| 216 | } |
| 217 | |
| 218 | /* |
| 219 | * Return a nonzero value iff `lk` is currently locked. |
| 220 | */ |
| 221 | static inline int is_lock_file_locked(struct lock_file *lk) |
| 222 | { |
| 223 | return is_tempfile_active(lk->tempfile); |
| 224 | } |
| 225 | |
| 226 | /* |
| 227 | * Append an appropriate error message to `buf` following the failure |
| 228 | * of `hold_lock_file_for_update()` to lock `path`. `err` should be the |
| 229 | * `errno` set by the failing call. |
| 230 | */ |
| 231 | void unable_to_lock_message(const char *path, int err, |
| 232 | struct strbuf *buf); |
| 233 | |
| 234 | /* |
| 235 | * Emit an appropriate error message and `die()` following the failure |
| 236 | * of `hold_lock_file_for_update()` to lock `path`. `err` should be the |
| 237 | * `errno` set by the failing |
| 238 | * call. |
| 239 | */ |
| 240 | NORETURN void unable_to_lock_die(const char *path, int err); |
| 241 | |
| 242 | /* |
| 243 | * Associate a stdio stream with the lockfile (which must still be |
| 244 | * open). Return `NULL` (*without* rolling back the lockfile) on |
| 245 | * error. The stream is closed automatically when |
| 246 | * `close_lock_file_gently()` is called or when the file is committed or |
| 247 | * rolled back. |
| 248 | */ |
| 249 | static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode) |
| 250 | { |
| 251 | return fdopen_tempfile(lk->tempfile, mode); |
| 252 | } |
| 253 | |
| 254 | /* |
| 255 | * Return the path of the lockfile. The return value is a pointer to a |
| 256 | * field within the lock_file object and should not be freed. |
| 257 | */ |
| 258 | static inline const char *get_lock_file_path(struct lock_file *lk) |
| 259 | { |
| 260 | return get_tempfile_path(lk->tempfile); |
| 261 | } |
| 262 | |
| 263 | static inline int get_lock_file_fd(struct lock_file *lk) |
| 264 | { |
| 265 | return get_tempfile_fd(lk->tempfile); |
| 266 | } |
| 267 | |
| 268 | static inline FILE *get_lock_file_fp(struct lock_file *lk) |
| 269 | { |
| 270 | return get_tempfile_fp(lk->tempfile); |
| 271 | } |
| 272 | |
| 273 | /* |
| 274 | * Return the path of the file that is locked by the specified |
| 275 | * lock_file object. The caller must free the memory. |
| 276 | */ |
| 277 | char *get_locked_file_path(struct lock_file *lk); |
| 278 | |
| 279 | /* |
| 280 | * If the lockfile is still open, close it (and the file pointer if it |
| 281 | * has been opened using `fdopen_lock_file()`) without renaming the |
| 282 | * lockfile over the file being locked. Return 0 upon success. On |
| 283 | * failure to `close(2)`, return a negative value (the lockfile is not |
| 284 | * rolled back). Usually `commit_lock_file()`, `commit_lock_file_to()`, |
| 285 | * or `rollback_lock_file()` should eventually be called. |
| 286 | */ |
| 287 | static inline int close_lock_file_gently(struct lock_file *lk) |
| 288 | { |
| 289 | return close_tempfile_gently(lk->tempfile); |
| 290 | } |
| 291 | |
| 292 | /* |
| 293 | * Re-open a lockfile that has been closed using `close_lock_file_gently()` |
| 294 | * but not yet committed or rolled back. This can be used to implement |
| 295 | * a sequence of operations like the following: |
| 296 | * |
| 297 | * * Lock file. |
| 298 | * |
| 299 | * * Write new contents to lockfile, then `close_lock_file_gently()` to |
| 300 | * cause the contents to be written to disk. |
| 301 | * |
| 302 | * * Pass the name of the lockfile to another program to allow it (and |
| 303 | * nobody else) to inspect the contents you wrote, while still |
| 304 | * holding the lock yourself. |
| 305 | * |
| 306 | * * `reopen_lock_file()` to reopen the lockfile, truncating the existing |
| 307 | * contents. Write out the new contents. |
| 308 | * |
| 309 | * * `commit_lock_file()` to make the final version permanent. |
| 310 | */ |
| 311 | static inline int reopen_lock_file(struct lock_file *lk) |
| 312 | { |
| 313 | return reopen_tempfile(lk->tempfile); |
| 314 | } |
| 315 | |
| 316 | /* |
| 317 | * Commit the change represented by `lk`: close the file descriptor |
| 318 | * and/or file pointer if they are still open and rename the lockfile |
| 319 | * to its final destination. Return 0 upon success. On failure, roll |
| 320 | * back the lock file and return -1, with `errno` set to the value |
| 321 | * from the failing call to `close(2)` or `rename(2)`. It is a bug to |
| 322 | * call `commit_lock_file()` for a `lock_file` object that is not |
| 323 | * currently locked. |
| 324 | */ |
| 325 | int commit_lock_file(struct lock_file *lk); |
| 326 | |
| 327 | /* |
| 328 | * Like `commit_lock_file()`, but rename the lockfile to the provided |
| 329 | * `path`. `path` must be on the same filesystem as the lock file. |
| 330 | */ |
| 331 | static inline int commit_lock_file_to(struct lock_file *lk, const char *path) |
| 332 | { |
| 333 | return rename_tempfile(&lk->tempfile, path); |
| 334 | } |
| 335 | |
| 336 | /* |
| 337 | * Roll back `lk`: close the file descriptor and/or file pointer and |
| 338 | * remove the lockfile and any associated PID file. It is a NOOP to |
| 339 | * call `rollback_lock_file()` for a `lock_file` object that has already |
| 340 | * been committed or rolled back. No error will be returned in this case. |
| 341 | */ |
| 342 | int rollback_lock_file(struct lock_file *lk); |
| 343 | |
| 344 | #endif /* LOCKFILE_H */ |