| #ifndef LOCKFILE_H |
| #define LOCKFILE_H |
| |
| /* |
| * File write-locks as used by Git. |
| * |
| * The lockfile API serves two purposes: |
| * |
| * * Mutual exclusion and atomic file updates. When we want to change |
| * a file, we create a lockfile `<filename>.lock`, write the new |
| * file contents into it, and then rename the lockfile to its final |
| * destination `<filename>`. We create the `<filename>.lock` file |
| * with `O_CREAT|O_EXCL` so that we can notice and fail if somebody |
| * else has already locked the file, then atomically rename the |
| * lockfile to its final destination to commit the changes and |
| * unlock the file. |
| * |
| * * Automatic cruft removal. If the program exits after we lock a |
| * file but before the changes have been committed, we want to make |
| * sure that we remove the lockfile. This is done by remembering the |
| * lockfiles we have created in a linked list and setting up an |
| * `atexit(3)` handler and a signal handler that clean up the |
| * lockfiles. This mechanism ensures that outstanding lockfiles are |
| * cleaned up if the program exits (including when `die()` is |
| * called) or if the program is terminated by a signal. |
| * |
| * Please note that lockfiles only block other writers. Readers do not |
| * block, but they are guaranteed to see either the old contents of |
| * the file or the new contents of the file (assuming that the |
| * filesystem implements `rename(2)` atomically). |
| * |
| * Most of the heavy lifting is done by the tempfile module (see |
| * "tempfile.h"). |
| * |
| * Calling sequence |
| * ---------------- |
| * |
| * The caller: |
| * |
| * * Allocates a `struct lock_file` either as a static variable or on |
| * the heap, initialized to zeros. Once you use the structure to |
| * call the `hold_lock_file_for_*()` family of functions, it belongs |
| * to the lockfile subsystem and its storage must remain valid |
| * throughout the life of the program (i.e. you cannot use an |
| * on-stack variable to hold this structure). |
| * |
| * * Attempts to create a lockfile by calling `hold_lock_file_for_update()`. |
| * |
| * * Writes new content for the destination file by either: |
| * |
| * * writing to the file descriptor returned by the |
| * `hold_lock_file_for_*()` functions (also available via |
| * `lock->fd`). |
| * |
| * * calling `fdopen_lock_file()` to get a `FILE` pointer for the |
| * open file and writing to the file using stdio. |
| * |
| * Note that the file descriptor returned by hold_lock_file_for_update() |
| * is marked O_CLOEXEC, so the new contents must be written by the |
| * current process, not a spawned one. |
| * |
| * When finished writing, the caller can: |
| * |
| * * Close the file descriptor and rename the lockfile to its final |
| * destination by calling `commit_lock_file()` or |
| * `commit_lock_file_to()`. |
| * |
| * * Close the file descriptor and remove the lockfile by calling |
| * `rollback_lock_file()`. |
| * |
| * * Close the file descriptor without removing or renaming the |
| * lockfile by calling `close_lock_file()`, and later call |
| * `commit_lock_file()`, `commit_lock_file_to()`, |
| * `rollback_lock_file()`, or `reopen_lock_file()`. |
| * |
| * Even after the lockfile is committed or rolled back, the |
| * `lock_file` object must not be freed or altered by the caller. |
| * However, it may be reused; just pass it to another call of |
| * `hold_lock_file_for_update()`. |
| * |
| * If the program exits before `commit_lock_file()`, |
| * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the |
| * tempfile module will close and remove the lockfile, thereby rolling |
| * back any uncommitted changes. |
| * |
| * If you need to close the file descriptor you obtained from a |
| * `hold_lock_file_for_*()` function yourself, do so by calling |
| * `close_lock_file()`. See "tempfile.h" for more information. |
| * |
| * |
| * Under the covers, a lockfile is just a tempfile with a few helper |
| * functions. In particular, the state diagram and the cleanup |
| * machinery are all implemented in the tempfile module. |
| * |
| * |
| * Error handling |
| * -------------- |
| * |
| * The `hold_lock_file_for_*()` functions return a file descriptor on |
| * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see |
| * "flags" below). On errors, `errno` describes the reason for |
| * failure. Errors can be reported by passing `errno` to |
| * `unable_to_lock_message()` or `unable_to_lock_die()`. |
| * |
| * Similarly, `commit_lock_file`, `commit_lock_file_to`, and |
| * `close_lock_file` return 0 on success. On failure they set `errno` |
| * appropriately, do their best to roll back the lockfile, and return |
| * -1. |
| */ |
| |
| #include "tempfile.h" |
| |
| struct lock_file { |
| struct tempfile tempfile; |
| }; |
| |
| /* String appended to a filename to derive the lockfile name: */ |
| #define LOCK_SUFFIX ".lock" |
| #define LOCK_SUFFIX_LEN 5 |
| |
| |
| /* |
| * Flags |
| * ----- |
| * |
| * The following flags can be passed to `hold_lock_file_for_update()`. |
| */ |
| |
| /* |
| * If a lock is already taken for the file, `die()` with an error |
| * message. If this flag is not specified, trying to lock a file that |
| * is already locked returns -1 to the caller. |
| */ |
| #define LOCK_DIE_ON_ERROR 1 |
| |
| /* |
| * Usually symbolic links in the destination path are resolved. This |
| * means that (1) the lockfile is created by adding ".lock" to the |
| * resolved path, and (2) upon commit, the resolved path is |
| * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile |
| * is created by adding ".lock" to the path argument itself. This |
| * option is used, for example, when detaching a symbolic reference, |
| * which for backwards-compatibility reasons, can be a symbolic link |
| * containing the name of the referred-to-reference. |
| */ |
| #define LOCK_NO_DEREF 2 |
| |
| /* |
| * Attempt to create a lockfile for the file at `path` and return a |
| * file descriptor for writing to it, or -1 on error. If the file is |
| * currently locked, retry with quadratic backoff for at least |
| * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if |
| * timeout_ms is -1, retry indefinitely. The flags argument and error |
| * handling are described above. |
| */ |
| extern int hold_lock_file_for_update_timeout( |
| struct lock_file *lk, const char *path, |
| int flags, long timeout_ms); |
| |
| /* |
| * Attempt to create a lockfile for the file at `path` and return a |
| * file descriptor for writing to it, or -1 on error. The flags |
| * argument and error handling are described above. |
| */ |
| static inline int hold_lock_file_for_update( |
| struct lock_file *lk, const char *path, |
| int flags) |
| { |
| return hold_lock_file_for_update_timeout(lk, path, flags, 0); |
| } |
| |
| /* |
| * Append an appropriate error message to `buf` following the failure |
| * of `hold_lock_file_for_update()` to lock `path`. `err` should be the |
| * `errno` set by the failing call. |
| */ |
| extern void unable_to_lock_message(const char *path, int err, |
| struct strbuf *buf); |
| |
| /* |
| * Emit an appropriate error message and `die()` following the failure |
| * of `hold_lock_file_for_update()` to lock `path`. `err` should be the |
| * `errno` set by the failing |
| * call. |
| */ |
| extern NORETURN void unable_to_lock_die(const char *path, int err); |
| |
| /* |
| * Associate a stdio stream with the lockfile (which must still be |
| * open). Return `NULL` (*without* rolling back the lockfile) on |
| * error. The stream is closed automatically when `close_lock_file()` |
| * is called or when the file is committed or rolled back. |
| */ |
| static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode) |
| { |
| return fdopen_tempfile(&lk->tempfile, mode); |
| } |
| |
| /* |
| * Return the path of the lockfile. The return value is a pointer to a |
| * field within the lock_file object and should not be freed. |
| */ |
| static inline const char *get_lock_file_path(struct lock_file *lk) |
| { |
| return get_tempfile_path(&lk->tempfile); |
| } |
| |
| static inline int get_lock_file_fd(struct lock_file *lk) |
| { |
| return get_tempfile_fd(&lk->tempfile); |
| } |
| |
| static inline FILE *get_lock_file_fp(struct lock_file *lk) |
| { |
| return get_tempfile_fp(&lk->tempfile); |
| } |
| |
| /* |
| * Return the path of the file that is locked by the specified |
| * lock_file object. The caller must free the memory. |
| */ |
| extern char *get_locked_file_path(struct lock_file *lk); |
| |
| /* |
| * If the lockfile is still open, close it (and the file pointer if it |
| * has been opened using `fdopen_lock_file()`) without renaming the |
| * lockfile over the file being locked. Return 0 upon success. On |
| * failure to `close(2)`, return a negative value and roll back the |
| * lock file. Usually `commit_lock_file()`, `commit_lock_file_to()`, |
| * or `rollback_lock_file()` should eventually be called if |
| * `close_lock_file()` succeeds. |
| */ |
| static inline int close_lock_file(struct lock_file *lk) |
| { |
| return close_tempfile(&lk->tempfile); |
| } |
| |
| /* |
| * Re-open a lockfile that has been closed using `close_lock_file()` |
| * but not yet committed or rolled back. This can be used to implement |
| * a sequence of operations like the following: |
| * |
| * * Lock file. |
| * |
| * * Write new contents to lockfile, then `close_lock_file()` to |
| * cause the contents to be written to disk. |
| * |
| * * Pass the name of the lockfile to another program to allow it (and |
| * nobody else) to inspect the contents you wrote, while still |
| * holding the lock yourself. |
| * |
| * * `reopen_lock_file()` to reopen the lockfile. Make further updates |
| * to the contents. |
| * |
| * * `commit_lock_file()` to make the final version permanent. |
| */ |
| static inline int reopen_lock_file(struct lock_file *lk) |
| { |
| return reopen_tempfile(&lk->tempfile); |
| } |
| |
| /* |
| * Commit the change represented by `lk`: close the file descriptor |
| * and/or file pointer if they are still open and rename the lockfile |
| * to its final destination. Return 0 upon success. On failure, roll |
| * back the lock file and return -1, with `errno` set to the value |
| * from the failing call to `close(2)` or `rename(2)`. It is a bug to |
| * call `commit_lock_file()` for a `lock_file` object that is not |
| * currently locked. |
| */ |
| extern int commit_lock_file(struct lock_file *lk); |
| |
| /* |
| * Like `commit_lock_file()`, but rename the lockfile to the provided |
| * `path`. `path` must be on the same filesystem as the lock file. |
| */ |
| static inline int commit_lock_file_to(struct lock_file *lk, const char *path) |
| { |
| return rename_tempfile(&lk->tempfile, path); |
| } |
| |
| /* |
| * Roll back `lk`: close the file descriptor and/or file pointer and |
| * remove the lockfile. It is a NOOP to call `rollback_lock_file()` |
| * for a `lock_file` object that has already been committed or rolled |
| * back. |
| */ |
| static inline void rollback_lock_file(struct lock_file *lk) |
| { |
| delete_tempfile(&lk->tempfile); |
| } |
| |
| #endif /* LOCKFILE_H */ |