| Michael Haggerty | 697cc8e | 2014-10-01 10:28:42 | [diff] [blame] | 1 | #ifndef LOCKFILE_H |
| 2 | #define LOCKFILE_H |
| 3 | |
| 4 | /* |
| 5 | * File write-locks as used by Git. |
| 6 | * |
| 7 | * For an overview of how to use the lockfile API, please see |
| 8 | * |
| 9 | * Documentation/technical/api-lockfile.txt |
| 10 | * |
| 11 | * This module keeps track of all locked files in lock_file_list for |
| 12 | * use at cleanup. This list and the lock_file objects that comprise |
| 13 | * it must be kept in self-consistent states at all time, because the |
| 14 | * program can be interrupted any time by a signal, in which case the |
| 15 | * signal handler will walk through the list attempting to clean up |
| 16 | * any open lock files. |
| 17 | * |
| 18 | * A lockfile is owned by the process that created it. The lock_file |
| 19 | * object has an "owner" field that records its owner. This field is |
| 20 | * used to prevent a forked process from closing a lockfile created by |
| 21 | * its parent. |
| 22 | * |
| 23 | * The possible states of a lock_file object are as follows: |
| 24 | * |
| 25 | * - Uninitialized. In this state the object's on_list field must be |
| 26 | * zero but the rest of its contents need not be initialized. As |
| 27 | * soon as the object is used in any way, it is irrevocably |
| 28 | * registered in the lock_file_list, and on_list is set. |
| 29 | * |
| 30 | * - Locked, lockfile open (after hold_lock_file_for_update(), |
| 31 | * hold_lock_file_for_append(), or reopen_lock_file()). In this |
| 32 | * state: |
| 33 | * - the lockfile exists |
| 34 | * - active is set |
| 35 | * - filename holds the filename of the lockfile |
| 36 | * - fd holds a file descriptor open for writing to the lockfile |
| Michael Haggerty | 013870c | 2014-10-01 11:14:47 | [diff] [blame] | 37 | * - fp holds a pointer to an open FILE object if and only if |
| 38 | * fdopen_lock_file() has been called on the object |
| Michael Haggerty | 697cc8e | 2014-10-01 10:28:42 | [diff] [blame] | 39 | * - owner holds the PID of the process that locked the file |
| 40 | * |
| 41 | * - Locked, lockfile closed (after successful close_lock_file()). |
| 42 | * Same as the previous state, except that the lockfile is closed |
| 43 | * and fd is -1. |
| 44 | * |
| 45 | * - Unlocked (after commit_lock_file(), commit_lock_file_to(), |
| 46 | * rollback_lock_file(), a failed attempt to lock, or a failed |
| 47 | * close_lock_file()). In this state: |
| 48 | * - active is unset |
| 49 | * - filename is empty (usually, though there are transitory |
| 50 | * states in which this condition doesn't hold). Client code should |
| 51 | * *not* rely on the filename being empty in this state. |
| 52 | * - fd is -1 |
| 53 | * - the object is left registered in the lock_file_list, and |
| 54 | * on_list is set. |
| 55 | */ |
| 56 | |
| 57 | struct lock_file { |
| 58 | struct lock_file *volatile next; |
| 59 | volatile sig_atomic_t active; |
| 60 | volatile int fd; |
| Michael Haggerty | 013870c | 2014-10-01 11:14:47 | [diff] [blame] | 61 | FILE *volatile fp; |
| Michael Haggerty | 697cc8e | 2014-10-01 10:28:42 | [diff] [blame] | 62 | volatile pid_t owner; |
| 63 | char on_list; |
| 64 | struct strbuf filename; |
| 65 | }; |
| 66 | |
| 67 | /* String appended to a filename to derive the lockfile name: */ |
| 68 | #define LOCK_SUFFIX ".lock" |
| 69 | #define LOCK_SUFFIX_LEN 5 |
| 70 | |
| 71 | #define LOCK_DIE_ON_ERROR 1 |
| 72 | #define LOCK_NO_DEREF 2 |
| 73 | |
| Michael Haggerty | 697cc8e | 2014-10-01 10:28:42 | [diff] [blame] | 74 | extern void unable_to_lock_message(const char *path, int err, |
| 75 | struct strbuf *buf); |
| 76 | extern NORETURN void unable_to_lock_die(const char *path, int err); |
| 77 | extern int hold_lock_file_for_update(struct lock_file *, const char *path, int); |
| 78 | extern int hold_lock_file_for_append(struct lock_file *, const char *path, int); |
| Michael Haggerty | 013870c | 2014-10-01 11:14:47 | [diff] [blame] | 79 | extern FILE *fdopen_lock_file(struct lock_file *, const char *mode); |
| Michael Haggerty | 697cc8e | 2014-10-01 10:28:42 | [diff] [blame] | 80 | extern char *get_locked_file_path(struct lock_file *); |
| 81 | extern int commit_lock_file_to(struct lock_file *, const char *path); |
| 82 | extern int commit_lock_file(struct lock_file *); |
| 83 | extern int reopen_lock_file(struct lock_file *); |
| 84 | extern int close_lock_file(struct lock_file *); |
| 85 | extern void rollback_lock_file(struct lock_file *); |
| 86 | |
| 87 | #endif /* LOCKFILE_H */ |
