]>
Commit | Line | Data |
---|---|---|
697cc8ef MH |
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 | |
013870cd MH |
37 | * - fp holds a pointer to an open FILE object if and only if |
38 | * fdopen_lock_file() has been called on the object | |
697cc8ef MH |
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; | |
013870cd | 61 | FILE *volatile fp; |
697cc8ef MH |
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 | ||
697cc8ef MH |
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); | |
013870cd | 79 | extern FILE *fdopen_lock_file(struct lock_file *, const char *mode); |
697cc8ef MH |
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 */ |