Sync with 2.4.3
[git/git.git] / lockfile.h
CommitLineData
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
57struct 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
74extern void unable_to_lock_message(const char *path, int err,
75 struct strbuf *buf);
76extern NORETURN void unable_to_lock_die(const char *path, int err);
044b6a9e
MH
77extern int hold_lock_file_for_update_timeout(
78 struct lock_file *lk, const char *path,
79 int flags, long timeout_ms);
80
81static inline int hold_lock_file_for_update(
82 struct lock_file *lk, const char *path,
83 int flags)
84{
85 return hold_lock_file_for_update_timeout(lk, path, flags, 0);
86}
87
88extern int hold_lock_file_for_append(struct lock_file *lk, const char *path,
89 int flags);
90
013870cd 91extern FILE *fdopen_lock_file(struct lock_file *, const char *mode);
697cc8ef
MH
92extern char *get_locked_file_path(struct lock_file *);
93extern int commit_lock_file_to(struct lock_file *, const char *path);
94extern int commit_lock_file(struct lock_file *);
95extern int reopen_lock_file(struct lock_file *);
96extern int close_lock_file(struct lock_file *);
97extern void rollback_lock_file(struct lock_file *);
98
99#endif /* LOCKFILE_H */