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 * 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. 104 */ 105 106struct lock_file { 107 struct lock_file *volatile next; 108 volatile sig_atomic_t active; 109 volatile int fd; 110 FILE *volatile fp; 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 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 */ 134#define LOCK_DIE_ON_ERROR 1 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 */ 146#define LOCK_NO_DEREF 2 147 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 */ 156extern int hold_lock_file_for_update_timeout( 157 struct lock_file *lk, const char *path, 158 int flags, long timeout_ms); 159 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 */ 165static 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 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 */ 178extern 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 */ 187extern void unable_to_lock_message(const char *path, int err, 188 struct strbuf *buf); 189 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 */ 196extern 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 */ 204extern FILE *fdopen_lock_file(struct lock_file *lk, const char *mode); 205 206extern int get_lock_file_fd(struct lock_file *lk); 207extern FILE *get_lock_file_fp(struct lock_file *lk); 208 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 */ 213extern 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 */ 224extern 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 */ 245extern 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 */ 256extern 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 */ 262extern 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 */ 270extern void rollback_lock_file(struct lock_file *lk); 271 272#endif /* LOCKFILE_H */